Settings

+ +

+ + {/* User Auth Token Section */} +

+ + User Auth Token + +

+ Give a website the ability to call this extension. +

+ + + + + {copied ? 'Token copied' : ''} + +

+ + {/* Hub link */} + + Manage Page Agent Hub + + + +

+ + Base URL + + setBaseURL(e.target.value)} + className="text-xs h-8" + /> +

+ + {/* Testing API notice */} + {isTestingEndpoint(baseURL) && ( +

+ + You are using our testing API. By using this you agree to the{' '} + + Terms of Use & Privacy Policy + +

+ )} + +

+ + Model + + setModel(e.target.value)} + className="text-xs h-8" + /> +

+ +

+ + API Key + +

+ setApiKey(e.target.value)} + className="text-xs h-8" + /> + +

+ +

+ Response Language + +

+ + {/* Advanced Config */} + + + {advancedOpen && ( + <> +

+ + Max Steps + + setMaxSteps(e.target.value ? Number(e.target.value) : undefined)} + className="text-xs h-8 [&::-webkit-inner-spin-button]:appearance-none [&::-webkit-outer-spin-button]:appearance-none [-moz-appearance:textfield]" + /> +

+ +

+ System Instruction +

setSystemInstruction(e.target.value)}
+							rows={3}
+							className="text-xs rounded-md border border-input bg-background px-3 py-2 resize-y min-h-[60px]"
+						/>
+					</div>
+
+					<label className="flex items-center justify-between cursor-pointer">
+						<span className="text-xs text-muted-foreground">Disable named tool_choice</span>
+						<Switch checked={disableNamedToolChoice} onCheckedChange={setDisableNamedToolChoice} />
+					</label>
+
+					<label className="flex items-center justify-between cursor-pointer">
+						<span className="text-xs text-muted-foreground">Experimental llms.txt support</span>
+						<Switch checked={experimentalLlmsTxt} onCheckedChange={setExperimentalLlmsTxt} />
+					</label>
+
+					<label className="flex items-center justify-between cursor-pointer">
+						<span className="text-xs text-muted-foreground">Experimental include all tabs</span>
+						<Switch
+							checked={experimentalIncludeAllTabs}
+							onCheckedChange={setExperimentalIncludeAllTabs}
+						/>
+					</label>
+				</>
+			)}
+
+			<div className="flex gap-2 mt-2">
+				<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 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">
+					<span>
+						Version <span className="font-mono">v{__VERSION__}</span>
+					</span>
+
+					<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>
+				</div>
+
+				<div className="flex flex-col items-end">
+					<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</span>
+					</a>
+				</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>
+	)
+}
diff --git a/packages/extension/src/components/ErrorBoundary.tsx b/packages/extension/src/components/ErrorBoundary.tsx
new file mode 100644
index 0000000..178779c
--- /dev/null
+++ b/packages/extension/src/components/ErrorBoundary.tsx
@@ -0,0 +1,60 @@
+import { AlertTriangle, Eraser, RotateCcw } from 'lucide-react'
+import { Component, type ErrorInfo, type ReactNode } from 'react'
+
+import { Button } from '@/components/ui/button'
+
+interface Props {
+	children: ReactNode
+}
+
+interface State {
+	hasError: boolean
+	error: Error | null
+}
+
+export class ErrorBoundary extends Component<Props, State> {
+	state: State = { hasError: false, error: null }
+
+	static getDerivedStateFromError(error: Error): State {
+		return { hasError: true, error }
+	}
+
+	componentDidCatch(error: Error, errorInfo: ErrorInfo) {
+		console.error('[ErrorBoundary]', error, errorInfo.componentStack)
+	}
+
+	handleReload = () => {
+		window.location.reload()
+	}
+
+	handleResetConfig = async () => {
+		await chrome.storage.local.remove(['llmConfig', 'language', 'advancedConfig'])
+		window.location.reload()
+	}
+
+	render() {
+		if (!this.state.hasError) {
+			return this.props.children
+		}
+
+		return (
+			<div className="flex flex-col items-center justify-center h-screen bg-background p-6 text-center">
+				<AlertTriangle className="size-12 text-destructive mb-4" />
+				<h2 className="text-lg font-semibold mb-2">Something went wrong</h2>
+				<p className="text-sm text-muted-foreground mb-4 max-w-xs">
+					{this.state.error?.message || 'An unexpected error occurred'}
+				</p>
+				<div className="flex gap-2">
+					<Button variant="outline" size="sm" onClick={this.handleResetConfig}>
+						<Eraser className="size-3.5 mr-2" />
+						Reset Config
+					</Button>
+					<Button variant="outline" size="sm" onClick={this.handleReload}>
+						<RotateCcw className="size-3.5 mr-2" />
+						Reload Panel
+					</Button>
+				</div>
+			</div>
+		)
+	}
+}
diff --git a/packages/extension/src/components/HistoryDetail.tsx b/packages/extension/src/components/HistoryDetail.tsx
new file mode 100644
index 0000000..9881b17
--- /dev/null
+++ b/packages/extension/src/components/HistoryDetail.tsx
@@ -0,0 +1,79 @@
+import { ArrowLeft, RotateCcw, Trash2 } from 'lucide-react'
+import { useEffect, useState } from 'react'
+
+import { Button } from '@/components/ui/button'
+import { type SessionRecord, deleteSession, getSession } from '@/lib/db'
+
+import { EventCard } from './cards'
+
+export function HistoryDetail({
+	sessionId,
+	onBack,
+	onRerun,
+}: {
+	sessionId: string
+	onBack: () => void
+	onRerun: (task: string) => 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 className="mt-2 flex items-center gap-2">
+					<button
+						type="button"
+						onClick={() => onRerun(session.task)}
+						className="flex items-center gap-1 text-[10px] text-muted-foreground hover:text-foreground transition-colors cursor-pointer disabled:opacity-50 disabled:cursor-not-allowed"
+					>
+						<RotateCcw className="size-3" />
+						Run again
+					</button>
+					<button
+						type="button"
+						onClick={async () => {
+							await deleteSession(sessionId)
+							onBack()
+						}}
+						className="flex items-center gap-1 text-[10px] text-muted-foreground hover:text-destructive transition-colors cursor-pointer"
+					>
+						<Trash2 className="size-3" />
+						Delete
+					</button>
+				</div>
+			</div>
+
+			{/* Events (read-only) */}
+			<div className="flex-1 overflow-y-auto p-3 space-y-2">
+				{session.history.map((event, index) => (
+					<EventCard key={index} event={event} />
+				))}
+			</div>
+		</div>
+	)
+}
diff --git a/packages/extension/src/components/HistoryList.tsx b/packages/extension/src/components/HistoryList.tsx
new file mode 100644
index 0000000..e582364
--- /dev/null
+++ b/packages/extension/src/components/HistoryList.tsx
@@ -0,0 +1,181 @@
+import {
+	ArrowDownToLine,
+	ArrowLeft,
+	CheckCircle,
+	History,
+	RotateCcw,
+	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'
+import { downloadHistoryExport } from '@/lib/history-export'
+
+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,
+	onRerun,
+}: {
+	onSelect: (id: string) => void
+	onBack: () => void
+	onRerun: (task: string) => void
+}) {
+	const [sessions, setSessions] = useState<SessionRecord[]>([])
+	const [loading, setLoading] = useState(true)
+
+	const load = useCallback(async () => {
+		try {
+			setSessions(await listSessions())
+		} catch (err) {
+			console.error('[HistoryList] Failed to load sessions:', err)
+		} finally {
+			setLoading(false)
+		}
+	}, [])
+
+	useEffect(() => {
+		load()
+	}, [load])
+
+	const handleDelete = async (e: React.MouseEvent, id: string) => {
+		e.stopPropagation()
+		await deleteSession(id)
+		setSessions((prev) => prev.filter((s) => s.id !== id))
+	}
+
+	const handleExport = (e: React.MouseEvent, session: SessionRecord) => {
+		e.stopPropagation()
+		downloadHistoryExport(session.task, session.createdAt, session.history)
+	}
+
+	const handleRerun = (e: React.MouseEvent, task: string) => {
+		e.stopPropagation()
+		onRerun(task)
+	}
+
+	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"
+					aria-label="Back"
+					title="Back"
+				>
+					<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 flex-col" aria-label="Loading history" aria-busy="true">
+						{[...Array(4)].map((_, i) => (
+							<div key={i} className="flex items-start gap-2 px-3 py-2.5 border-b">
+								<div className="size-3.5 mt-0.5 rounded-full bg-muted animate-pulse shrink-0" />
+								<div className="flex-1 space-y-1.5">
+									<div className="h-2.5 bg-muted animate-pulse rounded w-3/4" />
+									<div className="h-2 bg-muted animate-pulse rounded w-1/3" />
+								</div>
+							</div>
+						))}
+					</div>
+				)}
+
+				{!loading && sessions.length === 0 && (
+					<div className="flex flex-col items-center justify-center h-40 gap-2 text-muted-foreground">
+						<History className="size-8 opacity-30" />
+						<p className="text-xs">No history yet</p>
+					</div>
+				)}
+
+				{sessions.map((session) => (
+					<div
+						key={session.id}
+						role="button"
+						tabIndex={0}
+						onClick={() => 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>
+							<div className="flex items-center mt-0.5">
+								<p className="text-[10px] text-muted-foreground">
+									{timeAgo(session.createdAt)} · {session.history.length} steps
+								</p>
+								<div className="flex items-center gap-0.5 ml-auto opacity-0 group-hover:opacity-100 transition-opacity">
+									<button
+										type="button"
+										onClick={(e) => handleRerun(e, session.task)}
+										className="p-0.5 text-muted-foreground hover:text-foreground transition-colors cursor-pointer"
+										title="Run task again"
+										aria-label={`Run history task again: ${session.task}`}
+									>
+										<RotateCcw className="size-3" />
+									</button>
+									<button
+										type="button"
+										onClick={(e) => handleExport(e, session)}
+										className="p-1 text-muted-foreground hover:text-foreground transition-colors cursor-pointer"
+										title="Export history JSON"
+										aria-label={`Export history for ${session.task}`}
+									>
+										<ArrowDownToLine className="size-3" />
+									</button>
+									<button
+										type="button"
+										onClick={(e) => handleDelete(e, session.id)}
+										className="p-0.5 text-muted-foreground hover:text-destructive transition-colors cursor-pointer"
+										title="Delete history"
+										aria-label={`Delete history for ${session.task}`}
+									>
+										<Trash2 className="size-3" />
+									</button>
+								</div>
+							</div>
+						</div>
+					</div>
+				))}
+			</div>
+		</div>
+	)
+}
diff --git a/packages/extension/src/components/cards.tsx b/packages/extension/src/components/cards.tsx
new file mode 100644
index 0000000..cf1008b
--- /dev/null
+++ b/packages/extension/src/components/cards.tsx
@@ -0,0 +1,387 @@
+import type {
+	AgentActivity,
+	AgentErrorEvent,
+	AgentStepEvent,
+	HistoricalEvent,
+	ObservationEvent,
+	RetryEvent,
+} from '@page-agent/core'
+import {
+	CheckCircle,
+	Eye,
+	Globe,
+	Keyboard,
+	Mouse,
+	MoveVertical,
+	RefreshCw,
+	Sparkles,
+	XCircle,
+	Zap,
+} from 'lucide-react'
+import { Fragment, useState } from 'react'
+
+import { cn } from '@/lib/utils'
+
+// Result card for done action
+function ResultCard({
+	success,
+	text,
+	children,
+}: {
+	success: boolean
+	text: string
+	children?: React.ReactNode
+}) {
+	return (
+		<div
+			className={cn(
+				'rounded-lg border p-3',
+				success ? 'border-green-500/30 bg-green-500/10' : 'border-destructive/30 bg-destructive/10'
+			)}
+		>
+			<div className="flex items-center gap-2 mb-2">
+				{success ? (
+					<CheckCircle className="size-3.5 text-green-500" />
+				) : (
+					<XCircle className="size-3.5 text-destructive" />
+				)}
+				<span
+					className={cn(
+						'text-xs font-medium',
+						success ? 'text-green-600 dark:text-green-400' : 'text-destructive'
+					)}
+				>
+					Result: {success ? 'Success' : 'Failed'}
+				</span>
+			</div>
+			<p className="text-[12px] text-foreground pl-5 whitespace-pre-wrap">{text}</p>
+			{children}
+		</div>
+	)
+}
+
+// Single reflection item with truncation
+function ReflectionItem({ icon, value }: { icon: string; value: string }) {
+	const [expanded, setExpanded] = useState(false)
+
+	return (
+		<Fragment>
+			<span className="text-xs flex justify-center">{icon}</span>
+			<span
+				className={cn(
+					'text-[11px] text-muted-foreground cursor-pointer hover:text-muted-foreground/70',
+					!expanded && 'line-clamp-1'
+				)}
+				onClick={() => setExpanded(!expanded)}
+			>
+				{value}
+			</span>
+		</Fragment>
+	)
+}
+
+// Reflection section in step card
+function ReflectionSection({
+	reflection,
+}: {
+	reflection: {
+		evaluation_previous_goal?: string
+		memory?: string
+		next_goal?: string
+	}
+}) {
+	const items = [
+		{ icon: '☑️', label: 'eval', value: reflection.evaluation_previous_goal },
+		{ icon: '🧠', label: 'memory', value: reflection.memory },
+		{ icon: '🎯', label: 'goal', value: reflection.next_goal },
+	].filter((item) => item.value)
+
+	if (items.length === 0) return null
+
+	return (
+		<div className="mb-2">
+			{/* <div className="text-[11px] font-semibold text-foreground uppercase tracking-wide mb-2">
+				Reflection
+			</div> */}
+			<div className="grid grid-cols-[14px_1fr] gap-x-2 gap-y-2">
+				{items.map((item) => (
+					<ReflectionItem key={item.label} icon={item.icon} value={item.value!} />
+				))}
+			</div>
+		</div>
+	)
+}
+
+// Get icon for action type
+function ActionIcon({ name, className }: { name: string; className?: string }) {
+	const icons: Record<string, React.ReactNode> = {
+		click_element_by_index: <Mouse className={className} />,
+		input: <Keyboard className={className} />,
+		scroll: <MoveVertical className={className} />,
+		go_to_url: <Globe className={className} />,
+	}
+	return icons[name] || <Zap className={className} />
+}
+
+// Copy button with "Copied!" feedback
+function CopyButton({ text, label }: { text: string; label: string }) {
+	const [copied, setCopied] = useState(false)
+
+	return (
+		<button
+			type="button"
+			onClick={() => {
+				navigator.clipboard.writeText(text)
+				setCopied(true)
+				setTimeout(() => setCopied(false), 1500)
+			}}
+			className="text-[9px] text-muted-foreground hover:text-foreground transition-colors border px-1 rounded shrink-0 cursor-pointer backdrop-blur-xs"
+		>
+			{copied ? 'Copied!' : label}
+		</button>
+	)
+}
+
+// Extract message content by role from raw request
+function extractPrompt(rawRequest: unknown, role: 'system' | 'user'): string | null {
+	const messages = (rawRequest as { messages?: { role: string; content?: unknown }[] })?.messages
+	if (!messages) return null
+	if (!Array.isArray(messages)) return null
+	const msg =
+		role === 'system'
+			? messages.find((m) => m.role === role)
+			: messages.findLast((m) => m.role === role)
+	if (!msg?.content) return null
+	return typeof msg.content === 'string' ? msg.content : JSON.stringify(msg.content, null, 2)
+}
+
+// Raw request/response section (collapsible tabs, for debugging)
+function RawSection({ rawRequest, rawResponse }: { rawRequest?: unknown; rawResponse?: unknown }) {
+	const [activeTab, setActiveTab] = useState<'request' | 'response' | null>(null)
+
+	if (!rawRequest && !rawResponse) return null
+
+	const handleTabClick = (tab: 'request' | 'response') => {
+		setActiveTab(activeTab === tab ? null : tab)
+	}
+
+	const content =
+		activeTab === 'request' ? rawRequest : activeTab === 'response' ? rawResponse : null
+
+	const systemPrompt = activeTab === 'request' ? extractPrompt(rawRequest, 'system') : null
+	const userPrompt = activeTab === 'request' ? extractPrompt(rawRequest, 'user') : null
+
+	return (
+		<div className="mt-2 border-t border-dashed pt-2">
+			<div className="flex items-center gap-3 -my-1">
+				{rawRequest != null && (
+					<button
+						type="button"
+						onClick={() => handleTabClick('request')}
+						className={cn(
+							'text-[10px] mt-0.5 transition-colors border-b cursor-pointer',
+							activeTab === 'request'
+								? 'text-foreground border-foreground'
+								: 'text-muted-foreground border-transparent hover:text-foreground'
+						)}
+					>
+						Raw Request
+					</button>
+				)}
+				{rawResponse != null && (
+					<button
+						type="button"
+						onClick={() => handleTabClick('response')}
+						className={cn(
+							'text-[10px] mt-0.5 transition-colors border-b cursor-pointer',
+							activeTab === 'response'
+								? 'text-foreground border-foreground'
+								: 'text-muted-foreground border-transparent hover:text-foreground'
+						)}
+					>
+						Raw Response
+					</button>
+				)}
+			</div>
+			{content != null && (
+				<div className="relative mt-1.5">
+					<div className="absolute top-1 right-1 flex gap-1">
+						{systemPrompt && <CopyButton text={systemPrompt} label="Copy System" />}
+						{userPrompt && <CopyButton text={userPrompt} label="Copy User" />}
+						<CopyButton text={JSON.stringify(content, null, 4)} label="Copy" />
+					</div>
+					<pre className="p-2 pt-5 text-[10px] text-foreground/70 bg-muted rounded overflow-x-auto max-h-60 overflow-y-auto">
+						{JSON.stringify(content, null, 4)}
+					</pre>
+				</div>
+			)}
+		</div>
+	)
+}
+
+function StepCard({ event }: { event: AgentStepEvent }) {
+	return (
+		<div className="rounded-lg border-l-2 border-l-blue-500/50 border bg-muted/40 p-2.5">
+			<div className="text-[11px] font-semibold text-foreground tracking-wide mb-2">
+				Step #{event.stepIndex! + 1}
+			</div>
+
+			{/* Reflection */}
+			{event.reflection && <ReflectionSection reflection={event.reflection} />}
+
+			{/* Action */}
+			{event.action && (
+				<div>
+					<div className="text-[11px] font-semibold text-foreground tracking-wide mb-1">
+						Actions
+					</div>
+					<div className="flex items-start gap-2">
+						<ActionIcon
+							name={event.action.name}
+							className="size-3.5 text-blue-500 shrink-0 mt-0.5"
+						/>
+						<div className="flex-1 min-w-0">
+							<p className="text-xs text-foreground/80 mb-0.5 wrap-anywhere break-all line-clamp-1 hover:line-clamp-none">
+								<span className="font-medium text-foreground/70">{event.action.name}</span>
+								{event.action.name !== 'done' && (
+									<span className="text-muted-foreground/70 ml-1.5">
+										{JSON.stringify(event.action.input)}
+									</span>
+								)}
+							</p>
+							<p className="text-[11px] text-muted-foreground/70 grid grid-cols-[auto_1fr] gap-1.5">
+								<span className="">└</span>
+								<span className="wrap-anywhere break-all line-clamp-1 hover:line-clamp-3">
+									{event.action.output}
+								</span>
+							</p>
+						</div>
+					</div>
+				</div>
+			)}
+
+			{/* Raw Response */}
+			<RawSection rawRequest={event.rawRequest} rawResponse={event.rawResponse} />
+		</div>
+	)
+}
+
+function ObservationCard({ event }: { event: ObservationEvent }) {
+	return (
+		<div className="rounded-lg border-l-2 border-l-green-500/50 border bg-muted/40 p-2.5">
+			{/* <div className="text-[11px] font-semibold text-foreground uppercase tracking-wide mb-2">
+				Observation
+			</div> */}
+			<div className="flex items-start gap-2">
+				<Eye className="size-3.5 text-green-500 shrink-0 mt-0.5" />
+				<span className="text-[11px] text-muted-foreground">{event.content}</span>
+			</div>
+		</div>
+	)
+}
+
+function RetryCard({ event }: { event: RetryEvent }) {
+	return (
+		<div className="rounded-lg border border-amber-500/30 bg-amber-500/10 p-2.5">
+			<div className="flex items-start gap-1.5">
+				<RefreshCw className="size-3 text-amber-500 shrink-0 mt-0.5" />
+				<span className="text-xs text-amber-600 dark:text-amber-400">
+					{event.message} ({event.attempt}/{event.maxAttempts})
+				</span>
+			</div>
+		</div>
+	)
+}
+
+function ErrorCard({ event }: { event: AgentErrorEvent }) {
+	return (
+		<div className="rounded-lg border border-destructive/30 bg-destructive/10 p-2.5">
+			<div className="flex items-start gap-1.5">
+				<XCircle className="size-3 text-destructive shrink-0 mt-0.5" />
+				<span className="text-xs text-destructive">{event.message}</span>
+			</div>
+			<RawSection rawResponse={event.rawResponse} />
+		</div>
+	)
+}
+
+// History event card component
+export function EventCard({ event }: { event: HistoricalEvent }) {
+	// Done action - show as result card
+	if (event.type === 'step' && event.action?.name === 'done') {
+		const input = event.action.input as { text?: string; success?: boolean }
+		return (
+			<>
+				<StepCard event={event as AgentStepEvent} />
+				<ResultCard
+					success={input?.success ?? true}
+					text={input?.text || event.action.output || ''}
+				/>
+			</>
+		)
+	}
+
+	if (event.type === 'step') {
+		return <StepCard event={event as AgentStepEvent} />
+	}
+
+	if (event.type === 'observation') {
+		return <ObservationCard event={event as ObservationEvent} />
+	}
+
+	if (event.type === 'retry') {
+		return <RetryCard event={event as RetryEvent} />
+	}
+
+	if (event.type === 'error') {
+		return <ErrorCard event={event as AgentErrorEvent} />
+	}
+
+	return null
+}
+
+// Activity card with animation
+export function ActivityCard({ activity }: { activity: AgentActivity }) {
+	const getActivityInfo = () => {
+		switch (activity.type) {
+			case 'thinking':
+				return { text: 'Thinking...', color: 'text-blue-500' }
+			case 'executing':
+				return { text: `Executing ${activity.tool}...`, color: 'text-amber-500' }
+			case 'executed':
+				return { text: `Done: ${activity.tool}`, color: 'text-green-500' }
+			case 'retrying':
+				return {
+					text: `Retrying (${activity.attempt}/${activity.maxAttempts})...`,
+					color: 'text-amber-500',
+				}
+			case 'error':
+				return { text: activity.message, color: 'text-destructive' }
+		}
+	}
+
+	const info = getActivityInfo()
+
+	return (
+		<div className="flex items-center gap-2 rounded-lg border bg-muted/40 p-2.5 animate-pulse">
+			<div className="relative">
+				<Sparkles className={cn('size-3.5', info.color)} />
+				<span
+					className={cn(
+						'absolute -top-0.5 -right-0.5 size-1.5 rounded-full animate-ping',
+						activity.type === 'thinking'
+							? 'bg-blue-500'
+							: activity.type === 'executing'
+								? 'bg-amber-500'
+								: activity.type === 'retrying'
+									? 'bg-amber-500'
+									: activity.type === 'error'
+										? 'bg-destructive'
+										: 'bg-green-500'
+					)}
+				/>
+			</div>
+			<span className={cn('text-xs', info.color)}>{info.text}</span>
+		</div>
+	)
+}
diff --git a/packages/extension/src/components/misc.tsx b/packages/extension/src/components/misc.tsx
new file mode 100644
index 0000000..1779e02
--- /dev/null
+++ b/packages/extension/src/components/misc.tsx
@@ -0,0 +1,155 @@
+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
+export function StatusDot({ status }: { status: AgentStatus }) {
+	const colorClass = {
+		idle: 'bg-muted-foreground',
+		running: 'bg-blue-500',
+		completed: 'bg-green-500',
+		error: 'bg-destructive',
+		stopped: 'bg-muted-foreground',
+	}[status]
+
+	const label = {
+		idle: 'Ready',
+		running: 'Running',
+		completed: 'Done',
+		error: 'Error',
+		stopped: 'Stopped',
+	}[status]
+
+	return (
+		<div className="flex items-center gap-1.5 mr-2">
+			<span
+				className={cn('size-2 rounded-full', colorClass, status === 'running' && 'animate-pulse')}
+			/>
+			<span className="text-xs text-muted-foreground">{label}</span>
+		</div>
+	)
+}
+
+export function Logo({ className }: { className?: string }) {
+	return <img src="/assets/page-agent-256.webp" alt="Page Agent" className={cn('', className)} />
+}
+
+// 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(() => {
+		try {
+			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!)
+		} catch (e) {
+			console.warn('[MotionOverlay] Motion unavailable:', e)
+		}
+
+		return () => {
+			motionRef.current?.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 overflow-hidden"
+			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-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-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
+					startOnView={false}
+					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>
+	)
+}
diff --git a/packages/extension/src/components/ui/button.tsx b/packages/extension/src/components/ui/button.tsx
new file mode 100644
index 0000000..3579cbd
--- /dev/null
+++ b/packages/extension/src/components/ui/button.tsx
@@ -0,0 +1,60 @@
+import { Slot } from '@radix-ui/react-slot'
+import { type VariantProps, cva } from 'class-variance-authority'
+import * as React from 'react'
+
+import { cn } from '@/lib/utils'
+
+const buttonVariants = cva(
+	"inline-flex items-center justify-center gap-2 whitespace-nowrap rounded-md text-sm font-medium transition-all disabled:pointer-events-none disabled:opacity-50 [&_svg]:pointer-events-none [&_svg:not([class*='size-'])]:size-4 shrink-0 [&_svg]:shrink-0 outline-none focus-visible:border-ring focus-visible:ring-ring/50 focus-visible:ring-[3px] aria-invalid:ring-destructive/20 dark:aria-invalid:ring-destructive/40 aria-invalid:border-destructive",
+	{
+		variants: {
+			variant: {
+				default: 'bg-primary text-primary-foreground hover:bg-primary/90',
+				destructive:
+					'bg-destructive text-white hover:bg-destructive/90 focus-visible:ring-destructive/20 dark:focus-visible:ring-destructive/40 dark:bg-destructive/60',
+				outline:
+					'border bg-background shadow-xs hover:bg-accent hover:text-accent-foreground dark:bg-input/30 dark:border-input dark:hover:bg-input/50',
+				secondary: 'bg-secondary text-secondary-foreground hover:bg-secondary/80',
+				ghost: 'hover:bg-accent hover:text-accent-foreground dark:hover:bg-accent/50',
+				link: 'text-primary underline-offset-4 hover:underline',
+			},
+			size: {
+				default: 'h-9 px-4 py-2 has-[>svg]:px-3',
+				sm: 'h-8 rounded-md gap-1.5 px-3 has-[>svg]:px-2.5',
+				lg: 'h-10 rounded-md px-6 has-[>svg]:px-4',
+				icon: 'size-9',
+				'icon-sm': 'size-8',
+				'icon-lg': 'size-10',
+			},
+		},
+		defaultVariants: {
+			variant: 'default',
+			size: 'default',
+		},
+	}
+)
+
+function Button({
+	className,
+	variant = 'default',
+	size = 'default',
+	asChild = false,
+	...props
+}: React.ComponentProps<'button'> &
+	VariantProps<typeof buttonVariants> & {
+		asChild?: boolean
+	}) {
+	const Comp = asChild ? Slot : 'button'
+
+	return (
+		<Comp
+			data-slot="button"
+			data-variant={variant}
+			data-size={size}
+			className={cn(buttonVariants({ variant, size, className }))}
+			{...props}
+		/>
+	)
+}
+
+export { Button, buttonVariants }
diff --git a/packages/extension/src/components/ui/card.tsx b/packages/extension/src/components/ui/card.tsx
new file mode 100644
index 0000000..d0eb03e
--- /dev/null
+++ b/packages/extension/src/components/ui/card.tsx
@@ -0,0 +1,75 @@
+import * as React from 'react'
+
+import { cn } from '@/lib/utils'
+
+function Card({ className, ...props }: React.ComponentProps<'div'>) {
+	return (
+		<div
+			data-slot="card"
+			className={cn(
+				'bg-card text-card-foreground flex flex-col gap-6 rounded-xl border py-6 shadow-sm',
+				className
+			)}
+			{...props}
+		/>
+	)
+}
+
+function CardHeader({ className, ...props }: React.ComponentProps<'div'>) {
+	return (
+		<div
+			data-slot="card-header"
+			className={cn(
+				'@container/card-header grid auto-rows-min grid-rows-[auto_auto] items-start gap-2 px-6 has-data-[slot=card-action]:grid-cols-[1fr_auto] [.border-b]:pb-6',
+				className
+			)}
+			{...props}
+		/>
+	)
+}
+
+function CardTitle({ className, ...props }: React.ComponentProps<'div'>) {
+	return (
+		<div
+			data-slot="card-title"
+			className={cn('leading-none font-semibold', className)}
+			{...props}
+		/>
+	)
+}
+
+function CardDescription({ className, ...props }: React.ComponentProps<'div'>) {
+	return (
+		<div
+			data-slot="card-description"
+			className={cn('text-muted-foreground text-sm', className)}
+			{...props}
+		/>
+	)
+}
+
+function CardAction({ className, ...props }: React.ComponentProps<'div'>) {
+	return (
+		<div
+			data-slot="card-action"
+			className={cn('col-start-2 row-span-2 row-start-1 self-start justify-self-end', className)}
+			{...props}
+		/>
+	)
+}
+
+function CardContent({ className, ...props }: React.ComponentProps<'div'>) {
+	return <div data-slot="card-content" className={cn('px-6', className)} {...props} />
+}
+
+function CardFooter({ className, ...props }: React.ComponentProps<'div'>) {
+	return (
+		<div
+			data-slot="card-footer"
+			className={cn('flex items-center px-6 [.border-t]:pt-6', className)}
+			{...props}
+		/>
+	)
+}
+
+export { Card, CardHeader, CardFooter, CardTitle, CardAction, CardDescription, CardContent }
diff --git a/packages/extension/src/components/ui/field.tsx b/packages/extension/src/components/ui/field.tsx
new file mode 100644
index 0000000..4cdd5fb
--- /dev/null
+++ b/packages/extension/src/components/ui/field.tsx
@@ -0,0 +1,232 @@
+import { type VariantProps, cva } from 'class-variance-authority'
+import { useMemo } from 'react'
+
+import { Label } from '@/components/ui/label'
+import { Separator } from '@/components/ui/separator'
+import { cn } from '@/lib/utils'
+
+function FieldSet({ className, ...props }: React.ComponentProps<'fieldset'>) {
+	return (
+		<fieldset
+			data-slot="field-set"
+			className={cn(
+				'flex flex-col gap-6',
+				'has-[>[data-slot=checkbox-group]]:gap-3 has-[>[data-slot=radio-group]]:gap-3',
+				className
+			)}
+			{...props}
+		/>
+	)
+}
+
+function FieldLegend({
+	className,
+	variant = 'legend',
+	...props
+}: React.ComponentProps<'legend'> & { variant?: 'legend' | 'label' }) {
+	return (
+		<legend
+			data-slot="field-legend"
+			data-variant={variant}
+			className={cn(
+				'mb-3 font-medium',
+				'data-[variant=legend]:text-base',
+				'data-[variant=label]:text-sm',
+				className
+			)}
+			{...props}
+		/>
+	)
+}
+
+function FieldGroup({ className, ...props }: React.ComponentProps<'div'>) {
+	return (
+		<div
+			data-slot="field-group"
+			className={cn(
+				'group/field-group @container/field-group flex w-full flex-col gap-7 data-[slot=checkbox-group]:gap-3 [&>[data-slot=field-group]]:gap-4',
+				className
+			)}
+			{...props}
+		/>
+	)
+}
+
+const fieldVariants = cva('group/field flex w-full gap-3 data-[invalid=true]:text-destructive', {
+	variants: {
+		orientation: {
+			vertical: ['flex-col [&>*]:w-full [&>.sr-only]:w-auto'],
+			horizontal: [
+				'flex-row items-center',
+				'[&>[data-slot=field-label]]:flex-auto',
+				'has-[>[data-slot=field-content]]:items-start has-[>[data-slot=field-content]]:[&>[role=checkbox],[role=radio]]:mt-px',
+			],
+			responsive: [
+				'flex-col [&>*]:w-full [&>.sr-only]:w-auto @md/field-group:flex-row @md/field-group:items-center @md/field-group:[&>*]:w-auto',
+				'@md/field-group:[&>[data-slot=field-label]]:flex-auto',
+				'@md/field-group:has-[>[data-slot=field-content]]:items-start @md/field-group:has-[>[data-slot=field-content]]:[&>[role=checkbox],[role=radio]]:mt-px',
+			],
+		},
+	},
+	defaultVariants: {
+		orientation: 'vertical',
+	},
+})
+
+function Field({
+	className,
+	orientation = 'vertical',
+	...props
+}: React.ComponentProps<'div'> & VariantProps<typeof fieldVariants>) {
+	return (
+		<div
+			role="group"
+			data-slot="field"
+			data-orientation={orientation}
+			className={cn(fieldVariants({ orientation }), className)}
+			{...props}
+		/>
+	)
+}
+
+function FieldContent({ className, ...props }: React.ComponentProps<'div'>) {
+	return (
+		<div
+			data-slot="field-content"
+			className={cn('group/field-content flex flex-1 flex-col gap-1.5 leading-snug', className)}
+			{...props}
+		/>
+	)
+}
+
+function FieldLabel({ className, ...props }: React.ComponentProps<typeof Label>) {
+	return (
+		<Label
+			data-slot="field-label"
+			className={cn(
+				'group/field-label peer/field-label flex w-fit gap-2 leading-snug group-data-[disabled=true]/field:opacity-50',
+				'has-[>[data-slot=field]]:w-full has-[>[data-slot=field]]:flex-col has-[>[data-slot=field]]:rounded-md has-[>[data-slot=field]]:border [&>*]:data-[slot=field]:p-4',
+				'has-data-[state=checked]:bg-primary/5 has-data-[state=checked]:border-primary dark:has-data-[state=checked]:bg-primary/10',
+				className
+			)}
+			{...props}
+		/>
+	)
+}
+
+function FieldTitle({ className, ...props }: React.ComponentProps<'div'>) {
+	return (
+		<div
+			data-slot="field-label"
+			className={cn(
+				'flex w-fit items-center gap-2 text-sm leading-snug font-medium group-data-[disabled=true]/field:opacity-50',
+				className
+			)}
+			{...props}
+		/>
+	)
+}
+
+function FieldDescription({ className, ...props }: React.ComponentProps<'p'>) {
+	return (
+		<p
+			data-slot="field-description"
+			className={cn(
+				'text-muted-foreground text-sm leading-normal font-normal group-has-[[data-orientation=horizontal]]/field:text-balance',
+				'last:mt-0 nth-last-2:-mt-1 [[data-variant=legend]+&]:-mt-1.5',
+				'[&>a:hover]:text-primary [&>a]:underline [&>a]:underline-offset-4',
+				className
+			)}
+			{...props}
+		/>
+	)
+}
+
+function FieldSeparator({
+	children,
+	className,
+	...props
+}: React.ComponentProps<'div'> & {
+	children?: React.ReactNode
+}) {
+	return (
+		<div
+			data-slot="field-separator"
+			data-content={!!children}
+			className={cn(
+				'relative -my-2 h-5 text-sm group-data-[variant=outline]/field-group:-mb-2',
+				className
+			)}
+			{...props}
+		>
+			<Separator className="absolute inset-0 top-1/2" />
+			{children && (
+				<span
+					className="bg-background text-muted-foreground relative mx-auto block w-fit px-2"
+					data-slot="field-separator-content"
+				>
+					{children}
+				</span>
+			)}
+		</div>
+	)
+}
+
+function FieldError({
+	className,
+	children,
+	errors,
+	...props
+}: React.ComponentProps<'div'> & {
+	errors?: Array<{ message?: string } | undefined>
+}) {
+	const content = useMemo(() => {
+		if (children) {
+			return children
+		}
+
+		if (!errors?.length) {
+			return null
+		}
+
+		const uniqueErrors = [...new Map(errors.map((error) => [error?.message, error])).values()]
+
+		if (uniqueErrors?.length == 1) {
+			return uniqueErrors[0]?.message
+		}
+
+		return (
+			<ul className="ml-4 flex list-disc flex-col gap-1">
+				{uniqueErrors.map((error, index) => error?.message && <li key={index}>{error.message}</li>)}
+			</ul>
+		)
+	}, [children, errors])
+
+	if (!content) {
+		return null
+	}
+
+	return (
+		<div
+			role="alert"
+			data-slot="field-error"
+			className={cn('text-destructive text-sm font-normal', className)}
+			{...props}
+		>
+			{content}
+		</div>
+	)
+}
+
+export {
+	Field,
+	FieldLabel,
+	FieldDescription,
+	FieldError,
+	FieldGroup,
+	FieldLegend,
+	FieldSeparator,
+	FieldSet,
+	FieldContent,
+	FieldTitle,
+}
diff --git a/packages/extension/src/components/ui/hover-card.tsx b/packages/extension/src/components/ui/hover-card.tsx
new file mode 100644
index 0000000..502d2d5
--- /dev/null
+++ b/packages/extension/src/components/ui/hover-card.tsx
@@ -0,0 +1,36 @@
+import * as HoverCardPrimitive from '@radix-ui/react-hover-card'
+import * as React from 'react'
+
+import { cn } from '@/lib/utils'
+
+function HoverCard({ ...props }: React.ComponentProps<typeof HoverCardPrimitive.Root>) {
+	return <HoverCardPrimitive.Root data-slot="hover-card" {...props} />
+}
+
+function HoverCardTrigger({ ...props }: React.ComponentProps<typeof HoverCardPrimitive.Trigger>) {
+	return <HoverCardPrimitive.Trigger data-slot="hover-card-trigger" {...props} />
+}
+
+function HoverCardContent({
+	className,
+	align = 'center',
+	sideOffset = 4,
+	...props
+}: React.ComponentProps<typeof HoverCardPrimitive.Content>) {
+	return (
+		<HoverCardPrimitive.Portal data-slot="hover-card-portal">
+			<HoverCardPrimitive.Content
+				data-slot="hover-card-content"
+				align={align}
+				sideOffset={sideOffset}
+				className={cn(
+					'bg-popover text-popover-foreground data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 z-50 w-64 origin-(--radix-hover-card-content-transform-origin) rounded-md border p-4 shadow-md outline-hidden',
+					className
+				)}
+				{...props}
+			/>
+		</HoverCardPrimitive.Portal>
+	)
+}
+
+export { HoverCard, HoverCardTrigger, HoverCardContent }
diff --git a/packages/extension/src/components/ui/input-group.tsx b/packages/extension/src/components/ui/input-group.tsx
new file mode 100644
index 0000000..27681fc
--- /dev/null
+++ b/packages/extension/src/components/ui/input-group.tsx
@@ -0,0 +1,157 @@
+import { type VariantProps, cva } from 'class-variance-authority'
+import * as React from 'react'
+
+import { Button } from '@/components/ui/button'
+import { Input } from '@/components/ui/input'
+import { Textarea } from '@/components/ui/textarea'
+import { cn } from '@/lib/utils'
+
+function InputGroup({ className, ...props }: React.ComponentProps<'div'>) {
+	return (
+		<div
+			data-slot="input-group"
+			role="group"
+			className={cn(
+				'group/input-group border-input dark:bg-input/30 relative flex w-full items-center rounded-md border shadow-xs transition-[color,box-shadow] outline-none',
+				'h-9 min-w-0 has-[>textarea]:h-auto',
+
+				// Variants based on alignment.
+				'has-[>[data-align=inline-start]]:[&>input]:pl-2',
+				'has-[>[data-align=inline-end]]:[&>input]:pr-2',
+				'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 — 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',
+
+				className
+			)}
+			{...props}
+		/>
+	)
+}
+
+const inputGroupAddonVariants = cva(
+	"text-muted-foreground flex h-auto cursor-text items-center justify-center gap-2 py-1.5 text-sm font-medium select-none [&>svg:not([class*='size-'])]:size-4 [&>kbd]:rounded-[calc(var(--radius)-5px)] group-data-[disabled=true]/input-group:opacity-50",
+	{
+		variants: {
+			align: {
+				'inline-start': 'order-first pl-3 has-[>button]:ml-[-0.45rem] has-[>kbd]:ml-[-0.35rem]',
+				'inline-end': 'order-last pr-3 has-[>button]:mr-[-0.45rem] has-[>kbd]:mr-[-0.35rem]',
+				'block-start':
+					'order-first w-full justify-start px-3 pt-3 [.border-b]:pb-3 group-has-[>input]/input-group:pt-2.5',
+				'block-end':
+					'order-last w-full justify-start px-3 pb-3 [.border-t]:pt-3 group-has-[>input]/input-group:pb-2.5',
+			},
+		},
+		defaultVariants: {
+			align: 'inline-start',
+		},
+	}
+)
+
+function InputGroupAddon({
+	className,
+	align = 'inline-start',
+	...props
+}: React.ComponentProps<'div'> & VariantProps<typeof inputGroupAddonVariants>) {
+	return (
+		<div
+			role="group"
+			data-slot="input-group-addon"
+			data-align={align}
+			className={cn(inputGroupAddonVariants({ align }), className)}
+			onClick={(e) => {
+				if ((e.target as HTMLElement).closest('button')) {
+					return
+				}
+				e.currentTarget.parentElement?.querySelector('input')?.focus()
+			}}
+			{...props}
+		/>
+	)
+}
+
+const inputGroupButtonVariants = cva('text-sm shadow-none flex gap-2 items-center', {
+	variants: {
+		size: {
+			xs: "h-6 gap-1 px-2 rounded-[calc(var(--radius)-5px)] [&>svg:not([class*='size-'])]:size-3.5 has-[>svg]:px-2",
+			sm: 'h-8 px-2.5 gap-1.5 rounded-md has-[>svg]:px-2.5',
+			'icon-xs': 'size-6 rounded-[calc(var(--radius)-5px)] p-0 has-[>svg]:p-0',
+			'icon-sm': 'size-8 p-0 has-[>svg]:p-0',
+		},
+	},
+	defaultVariants: {
+		size: 'xs',
+	},
+})
+
+function InputGroupButton({
+	className,
+	type = 'button',
+	variant = 'ghost',
+	size = 'xs',
+	...props
+}: Omit<React.ComponentProps<typeof Button>, 'size'> &
+	VariantProps<typeof inputGroupButtonVariants>) {
+	return (
+		<Button
+			type={type}
+			data-size={size}
+			variant={variant}
+			className={cn(inputGroupButtonVariants({ size }), className)}
+			{...props}
+		/>
+	)
+}
+
+function InputGroupText({ className, ...props }: React.ComponentProps<'span'>) {
+	return (
+		<span
+			className={cn(
+				"text-muted-foreground flex items-center gap-2 text-sm [&_svg]:pointer-events-none [&_svg:not([class*='size-'])]:size-4",
+				className
+			)}
+			{...props}
+		/>
+	)
+}
+
+function InputGroupInput({ className, ...props }: React.ComponentProps<'input'>) {
+	return (
+		<Input
+			data-slot="input-group-control"
+			className={cn(
+				'flex-1 rounded-none border-0 bg-transparent shadow-none focus-visible:ring-0 dark:bg-transparent',
+				className
+			)}
+			{...props}
+		/>
+	)
+}
+
+function InputGroupTextarea({ className, ...props }: React.ComponentProps<'textarea'>) {
+	return (
+		<Textarea
+			data-slot="input-group-control"
+			className={cn(
+				'flex-1 resize-none rounded-none border-0 bg-transparent py-3 shadow-none focus-visible:ring-0 dark:bg-transparent',
+				className
+			)}
+			{...props}
+		/>
+	)
+}
+
+export {
+	InputGroup,
+	InputGroupAddon,
+	InputGroupButton,
+	InputGroupText,
+	InputGroupInput,
+	InputGroupTextarea,
+}
diff --git a/packages/extension/src/components/ui/input.tsx b/packages/extension/src/components/ui/input.tsx
new file mode 100644
index 0000000..f40ca3e
--- /dev/null
+++ b/packages/extension/src/components/ui/input.tsx
@@ -0,0 +1,21 @@
+import * as React from 'react'
+
+import { cn } from '@/lib/utils'
+
+function Input({ className, type, ...props }: React.ComponentProps<'input'>) {
+	return (
+		<input
+			type={type}
+			data-slot="input"
+			className={cn(
+				'file:text-foreground placeholder:text-muted-foreground selection:bg-primary selection:text-primary-foreground dark:bg-input/30 border-input h-9 w-full min-w-0 rounded-md border bg-transparent px-3 py-1 text-base shadow-xs transition-[color,box-shadow] outline-none file:inline-flex file:h-7 file:border-0 file:bg-transparent file:text-sm file:font-medium disabled:pointer-events-none disabled:cursor-not-allowed disabled:opacity-50 md:text-sm',
+				'focus-visible:border-ring focus-visible:ring-ring/50 focus-visible:ring-[3px]',
+				'aria-invalid:ring-destructive/20 dark:aria-invalid:ring-destructive/40 aria-invalid:border-destructive',
+				className
+			)}
+			{...props}
+		/>
+	)
+}
+
+export { Input }
diff --git a/packages/extension/src/components/ui/item.tsx b/packages/extension/src/components/ui/item.tsx
new file mode 100644
index 0000000..032040f
--- /dev/null
+++ b/packages/extension/src/components/ui/item.tsx
@@ -0,0 +1,172 @@
+import { Slot } from '@radix-ui/react-slot'
+import { type VariantProps, cva } from 'class-variance-authority'
+import * as React from 'react'
+
+import { Separator } from '@/components/ui/separator'
+import { cn } from '@/lib/utils'
+
+function ItemGroup({ className, ...props }: React.ComponentProps<'div'>) {
+	return (
+		<div
+			role="list"
+			data-slot="item-group"
+			className={cn('group/item-group flex flex-col', className)}
+			{...props}
+		/>
+	)
+}
+
+function ItemSeparator({ className, ...props }: React.ComponentProps<typeof Separator>) {
+	return (
+		<Separator
+			data-slot="item-separator"
+			orientation="horizontal"
+			className={cn('my-0', className)}
+			{...props}
+		/>
+	)
+}
+
+const itemVariants = cva(
+	'group/item flex items-center border border-transparent text-sm rounded-md transition-colors [a]:hover:bg-accent/50 [a]:transition-colors duration-100 flex-wrap outline-none focus-visible:border-ring focus-visible:ring-ring/50 focus-visible:ring-[3px]',
+	{
+		variants: {
+			variant: {
+				default: 'bg-transparent',
+				outline: 'border-border',
+				muted: 'bg-muted/50',
+			},
+			size: {
+				default: 'p-4 gap-4 ',
+				sm: 'py-3 px-4 gap-2.5',
+			},
+		},
+		defaultVariants: {
+			variant: 'default',
+			size: 'default',
+		},
+	}
+)
+
+function Item({
+	className,
+	variant = 'default',
+	size = 'default',
+	asChild = false,
+	...props
+}: React.ComponentProps<'div'> & VariantProps<typeof itemVariants> & { asChild?: boolean }) {
+	const Comp = asChild ? Slot : 'div'
+	return (
+		<Comp
+			data-slot="item"
+			data-variant={variant}
+			data-size={size}
+			className={cn(itemVariants({ variant, size, className }))}
+			{...props}
+		/>
+	)
+}
+
+const itemMediaVariants = cva(
+	'flex shrink-0 items-center justify-center gap-2 group-has-[[data-slot=item-description]]/item:self-start [&_svg]:pointer-events-none group-has-[[data-slot=item-description]]/item:translate-y-0.5',
+	{
+		variants: {
+			variant: {
+				default: 'bg-transparent',
+				icon: "size-8 border rounded-sm bg-muted [&_svg:not([class*='size-'])]:size-4",
+				image: 'size-10 rounded-sm overflow-hidden [&_img]:size-full [&_img]:object-cover',
+			},
+		},
+		defaultVariants: {
+			variant: 'default',
+		},
+	}
+)
+
+function ItemMedia({
+	className,
+	variant = 'default',
+	...props
+}: React.ComponentProps<'div'> & VariantProps<typeof itemMediaVariants>) {
+	return (
+		<div
+			data-slot="item-media"
+			data-variant={variant}
+			className={cn(itemMediaVariants({ variant, className }))}
+			{...props}
+		/>
+	)
+}
+
+function ItemContent({ className, ...props }: React.ComponentProps<'div'>) {
+	return (
+		<div
+			data-slot="item-content"
+			className={cn('flex flex-1 flex-col gap-1 [&+[data-slot=item-content]]:flex-none', className)}
+			{...props}
+		/>
+	)
+}
+
+function ItemTitle({ className, ...props }: React.ComponentProps<'div'>) {
+	return (
+		<div
+			data-slot="item-title"
+			className={cn('flex w-fit items-center gap-2 text-sm leading-snug font-medium', className)}
+			{...props}
+		/>
+	)
+}
+
+function ItemDescription({ className, ...props }: React.ComponentProps<'p'>) {
+	return (
+		<p
+			data-slot="item-description"
+			className={cn(
+				'text-muted-foreground line-clamp-2 text-sm leading-normal font-normal text-balance',
+				'[&>a:hover]:text-primary [&>a]:underline [&>a]:underline-offset-4',
+				className
+			)}
+			{...props}
+		/>
+	)
+}
+
+function ItemActions({ className, ...props }: React.ComponentProps<'div'>) {
+	return (
+		<div data-slot="item-actions" className={cn('flex items-center gap-2', className)} {...props} />
+	)
+}
+
+function ItemHeader({ className, ...props }: React.ComponentProps<'div'>) {
+	return (
+		<div
+			data-slot="item-header"
+			className={cn('flex basis-full items-center justify-between gap-2', className)}
+			{...props}
+		/>
+	)
+}
+
+function ItemFooter({ className, ...props }: React.ComponentProps<'div'>) {
+	return (
+		<div
+			data-slot="item-footer"
+			className={cn('flex basis-full items-center justify-between gap-2', className)}
+			{...props}
+		/>
+	)
+}
+
+export {
+	Item,
+	ItemMedia,
+	ItemContent,
+	ItemActions,
+	ItemGroup,
+	ItemSeparator,
+	ItemTitle,
+	ItemDescription,
+	ItemHeader,
+	ItemFooter,
+}
diff --git a/packages/extension/src/components/ui/label.tsx b/packages/extension/src/components/ui/label.tsx
new file mode 100644
index 0000000..0ac78b1
--- /dev/null
+++ b/packages/extension/src/components/ui/label.tsx
@@ -0,0 +1,19 @@
+import * as LabelPrimitive from '@radix-ui/react-label'
+import * as React from 'react'
+
+import { cn } from '@/lib/utils'
+
+function Label({ className, ...props }: React.ComponentProps<typeof LabelPrimitive.Root>) {
+	return (
+		<LabelPrimitive.Root
+			data-slot="label"
+			className={cn(
+				'flex items-center gap-2 text-sm leading-none font-medium select-none group-data-[disabled=true]:pointer-events-none group-data-[disabled=true]:opacity-50 peer-disabled:cursor-not-allowed peer-disabled:opacity-50',
+				className
+			)}
+			{...props}
+		/>
+	)
+}
+
+export { Label }
diff --git a/packages/extension/src/components/ui/separator.tsx b/packages/extension/src/components/ui/separator.tsx
new file mode 100644
index 0000000..ae51953
--- /dev/null
+++ b/packages/extension/src/components/ui/separator.tsx
@@ -0,0 +1,26 @@
+import * as SeparatorPrimitive from '@radix-ui/react-separator'
+import * as React from 'react'
+
+import { cn } from '@/lib/utils'
+
+function Separator({
+	className,
+	orientation = 'horizontal',
+	decorative = true,
+	...props
+}: React.ComponentProps<typeof SeparatorPrimitive.Root>) {
+	return (
+		<SeparatorPrimitive.Root
+			data-slot="separator"
+			decorative={decorative}
+			orientation={orientation}
+			className={cn(
+				'bg-border shrink-0 data-[orientation=horizontal]:h-px data-[orientation=horizontal]:w-full data-[orientation=vertical]:h-full data-[orientation=vertical]:w-px',
+				className
+			)}
+			{...props}
+		/>
+	)
+}
+
+export { Separator }
diff --git a/packages/extension/src/components/ui/sonner.tsx b/packages/extension/src/components/ui/sonner.tsx
new file mode 100644
index 0000000..21835dc
--- /dev/null
+++ b/packages/extension/src/components/ui/sonner.tsx
@@ -0,0 +1,38 @@
+import {
+	CircleCheckIcon,
+	InfoIcon,
+	Loader2Icon,
+	OctagonXIcon,
+	TriangleAlertIcon,
+} from 'lucide-react'
+import { useTheme } from 'next-themes'
+import { Toaster as Sonner, type ToasterProps } from 'sonner'
+
+const Toaster = ({ ...props }: ToasterProps) => {
+	const { theme = 'system' } = useTheme()
+
+	return (
+		<Sonner
+			theme={theme as ToasterProps['theme']}
+			className="toaster group"
+			icons={{
+				success: <CircleCheckIcon className="size-4" />,
+				info: <InfoIcon className="size-4" />,
+				warning: <TriangleAlertIcon className="size-4" />,
+				error: <OctagonXIcon className="size-4" />,
+				loading: <Loader2Icon className="size-4 animate-spin" />,
+			}}
+			style={
+				{
+					'--normal-bg': 'var(--popover)',
+					'--normal-text': 'var(--popover-foreground)',
+					'--normal-border': 'var(--border)',
+					'--border-radius': 'var(--radius)',
+				} as React.CSSProperties
+			}
+			{...props}
+		/>
+	)
+}
+
+export { Toaster }
diff --git a/packages/extension/src/components/ui/spinner.tsx b/packages/extension/src/components/ui/spinner.tsx
new file mode 100644
index 0000000..b45047c
--- /dev/null
+++ b/packages/extension/src/components/ui/spinner.tsx
@@ -0,0 +1,16 @@
+import { Loader2Icon } from 'lucide-react'
+
+import { cn } from '@/lib/utils'
+
+function Spinner({ className, ...props }: React.ComponentProps<'svg'>) {
+	return (
+		<Loader2Icon
+			role="status"
+			aria-label="Loading"
+			className={cn('size-4 animate-spin', className)}
+			{...props}
+		/>
+	)
+}
+
+export { Spinner }
diff --git a/packages/extension/src/components/ui/switch.tsx b/packages/extension/src/components/ui/switch.tsx
new file mode 100644
index 0000000..31fa2cb
--- /dev/null
+++ b/packages/extension/src/components/ui/switch.tsx
@@ -0,0 +1,26 @@
+import * as SwitchPrimitive from '@radix-ui/react-switch'
+import * as React from 'react'
+
+import { cn } from '@/lib/utils'
+
+function Switch({ className, ...props }: React.ComponentProps<typeof SwitchPrimitive.Root>) {
+	return (
+		<SwitchPrimitive.Root
+			data-slot="switch"
+			className={cn(
+				'peer data-[state=checked]:bg-primary data-[state=unchecked]:bg-input focus-visible:border-ring focus-visible:ring-ring/50 dark:data-[state=unchecked]:bg-input/80 inline-flex h-[1.15rem] w-8 shrink-0 cursor-pointer items-center rounded-full border border-transparent shadow-xs transition-all outline-none focus-visible:ring-[3px] disabled:cursor-not-allowed disabled:opacity-50',
+				className
+			)}
+			{...props}
+		>
+			<SwitchPrimitive.Thumb
+				data-slot="switch-thumb"
+				className={cn(
+					'bg-background dark:data-[state=unchecked]:bg-foreground dark:data-[state=checked]:bg-primary-foreground pointer-events-none block size-4 rounded-full ring-0 transition-transform data-[state=checked]:translate-x-[calc(100%-2px)] data-[state=unchecked]:translate-x-0'
+				)}
+			/>
+		</SwitchPrimitive.Root>
+	)
+}
+
+export { Switch }
diff --git a/packages/extension/src/components/ui/textarea.tsx b/packages/extension/src/components/ui/textarea.tsx
new file mode 100644
index 0000000..3658151
--- /dev/null
+++ b/packages/extension/src/components/ui/textarea.tsx
@@ -0,0 +1,18 @@
+import * as React from 'react'
+
+import { cn } from '@/lib/utils'
+
+function Textarea({ className, ...props }: React.ComponentProps<'textarea'>) {
+	return (
+		<textarea
+			data-slot="textarea"
+			className={cn(
+				'border-input placeholder:text-muted-foreground focus-visible:border-ring focus-visible:ring-ring/50 aria-invalid:ring-destructive/20 dark:aria-invalid:ring-destructive/40 aria-invalid:border-destructive dark:bg-input/30 flex field-sizing-content min-h-16 w-full rounded-md border bg-transparent px-3 py-2 text-base shadow-xs transition-[color,box-shadow] outline-none focus-visible:ring-[3px] disabled:cursor-not-allowed disabled:opacity-50 md:text-sm',
+				className
+			)}
+			{...props}
+		/>
+	)
+}
+
+export { Textarea }
diff --git a/packages/extension/src/components/ui/typing-animation.tsx b/packages/extension/src/components/ui/typing-animation.tsx
new file mode 100644
index 0000000..f9898df
--- /dev/null
+++ b/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>
+	)
+}
diff --git a/packages/extension/src/entrypoints/background.ts b/packages/extension/src/entrypoints/background.ts
new file mode 100644
index 0000000..cda1cc9
--- /dev/null
+++ b/packages/extension/src/entrypoints/background.ts
@@ -0,0 +1,59 @@
+import { handlePageControlMessage } from '@/agent/RemotePageController.background'
+import { handleTabControlMessage } from '@/agent/TabsController.background'
+
+export default defineBackground(() => {
+	console.log('[Background] Service Worker started')
+
+	// generate user auth token
+
+	chrome.storage.local.get('PageAgentExtUserAuthToken').then((result) => {
+		if (result.PageAgentExtUserAuthToken) return
+
+		const userAuthToken = crypto.randomUUID()
+		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
+		}
+	})
+
+	// external messages (from localhost launcher page via externally_connectable)
+
+	chrome.runtime.onMessageExternal.addListener((message, sender, sendResponse) => {
+		if (message.type === 'OPEN_HUB') {
+			openOrFocusHubTab(message.wsPort).then(() => {
+				if (sender.tab?.id) chrome.tabs.remove(sender.tab.id)
+				sendResponse({ ok: true })
+			})
+			return true
+		}
+	})
+
+	// setup
+
+	chrome.sidePanel.setPanelBehavior({ openPanelOnActionClick: true }).catch(() => {})
+})
+
+async function openOrFocusHubTab(wsPort: number) {
+	const hubUrl = chrome.runtime.getURL('hub.html')
+	const existing = await chrome.tabs.query({ url: `${hubUrl}*` })
+
+	if (existing.length > 0 && existing[0].id) {
+		await chrome.tabs.update(existing[0].id, {
+			active: true,
+			url: `${hubUrl}?ws=${wsPort}`,
+		})
+		return
+	}
+
+	await chrome.tabs.create({ url: `${hubUrl}?ws=${wsPort}`, pinned: true })
+}
diff --git a/packages/extension/src/entrypoints/content.ts b/packages/extension/src/entrypoints/content.ts
new file mode 100644
index 0000000..e7913bb
--- /dev/null
+++ b/packages/extension/src/entrypoints/content.ts
@@ -0,0 +1,164 @@
+import { initPageController } from '@/agent/RemotePageController.content'
+
+// import { DEMO_CONFIG } from '@/agent/constants'
+
+const DEBUG_PREFIX = '[Content]'
+
+export default defineContentScript({
+	matches: ['<all_urls>'],
+	runAt: 'document_end',
+
+	main() {
+		console.debug(`${DEBUG_PREFIX} Loaded on ${window.location.href}`)
+		initPageController()
+
+		// if auth token matches, expose agent to page
+		chrome.storage.local.get('PageAgentExtUserAuthToken').then((result) => {
+			// extension side token.
+			// @note this is isolated world. it is safe to assume user script cannot access it
+			const extToken = result.PageAgentExtUserAuthToken
+			if (!extToken) return
+
+			// page side token
+			const pageToken = localStorage.getItem('PageAgentExtUserAuthToken')
+			if (!pageToken) return
+
+			if (pageToken !== extToken) return
+
+			console.log('[PageAgentExt]: Auth tokens match. Exposing agent to page.')
+
+			// add isolated world script
+			exposeAgentToPage().then(
+				// add main-world script
+				() => injectScript('/main-world.js')
+			)
+		})
+	},
+})
+
+async function exposeAgentToPage() {
+	const { MultiPageAgent } = await import('@/agent/MultiPageAgent')
+	console.log('[PageAgentExt]: MultiPageAgent loaded')
+
+	/**
+	 * singleton MultiPageAgent to handle requests from the page
+	 */
+	let multiPageAgent: InstanceType<typeof MultiPageAgent> | null = null
+
+	window.addEventListener('message', async (e) => {
+		if (e.source !== window) return
+
+		const data = e.data
+		if (typeof data !== 'object' || data === null) return
+		if (data.channel !== 'PAGE_AGENT_EXT_REQUEST') return
+
+		const { action, payload, id } = data
+
+		switch (action) {
+			case 'execute': {
+				// singleton check
+				if (multiPageAgent && multiPageAgent.status === 'running') {
+					window.postMessage(
+						{
+							channel: 'PAGE_AGENT_EXT_RESPONSE',
+							id,
+							action: 'execute_result',
+							error: 'Agent is already running a task. Please wait until it finishes.',
+						},
+						'*'
+					)
+					return
+				}
+
+				try {
+					const { task, config } = payload
+					const { systemInstruction, ...agentConfig } = config
+
+					// Dispose old instance before creating new one
+					multiPageAgent?.dispose()
+
+					multiPageAgent = new MultiPageAgent({
+						...agentConfig,
+						instructions: systemInstruction ? { system: systemInstruction } : undefined,
+					})
+
+					// 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)
+
+					window.postMessage(
+						{
+							channel: 'PAGE_AGENT_EXT_RESPONSE',
+							id,
+							action: 'execute_result',
+							payload: result,
+						},
+						'*'
+					)
+				} catch (error) {
+					window.postMessage(
+						{
+							channel: 'PAGE_AGENT_EXT_RESPONSE',
+							id,
+							action: 'execute_result',
+							error: (error as Error).message,
+						},
+						'*'
+					)
+				}
+
+				break
+			}
+
+			case 'stop': {
+				multiPageAgent?.stop()
+				break
+			}
+
+			default:
+				console.warn(`${DEBUG_PREFIX} Unknown action from page:`, action)
+				break
+		}
+	})
+}
diff --git a/packages/extension/src/entrypoints/hub/App.tsx b/packages/extension/src/entrypoints/hub/App.tsx
new file mode 100644
index 0000000..b9d8dd3
--- /dev/null
+++ b/packages/extension/src/entrypoints/hub/App.tsx
@@ -0,0 +1,250 @@
+import { FoldVertical, Plug, PlugZap, Square, UnfoldVertical, Unplug } from 'lucide-react'
+import { useEffect, useRef, useState } from 'react'
+
+import { useAgent } from '@/agent/useAgent'
+import { ActivityCard, EventCard } from '@/components/cards'
+import { Logo, MotionOverlay, StatusDot } from '@/components/misc'
+import { Button } from '@/components/ui/button'
+import { Switch } from '@/components/ui/switch'
+
+import { useHubWs } from './hub-ws'
+
+export default function App() {
+	const { status, history, activity, currentTask, config, execute, stop, configure } = useAgent()
+	const { wsState } = useHubWs(execute, stop, configure, config)
+
+	const historyRef = useRef<HTMLDivElement>(null)
+
+	useEffect(() => {
+		if (historyRef.current) {
+			historyRef.current.scrollTop = historyRef.current.scrollHeight
+		}
+	}, [history, activity])
+
+	const isRunning = status === 'running'
+	const WsIcon = wsState === 'connected' ? PlugZap : wsState === 'connecting' ? Plug : Unplug
+	const wsLabel = {
+		connected: 'Connected',
+		connecting: 'Connecting…',
+		disconnected: new URLSearchParams(location.search).get('ws') ? 'Disconnected' : 'No connection',
+	}[wsState]
+
+	return (
+		<div className="flex h-screen bg-background">
+			{/* Left — Protocol docs */}
+			<aside className="w-80 shrink-0 border-r flex flex-col bg-muted/20">
+				<a
+					href="https://alibaba.github.io/page-agent/"
+					target="_blank"
+					rel="noopener noreferrer"
+					className="flex items-center gap-2 px-5 h-12 border-b hover:bg-muted/30 transition-colors"
+				>
+					<Logo className="size-5" />
+					<span className="text-sm font-semibold tracking-tight">Page Agent Hub</span>
+					<span className="text-[9px] font-medium uppercase tracking-wider text-amber-600 bg-amber-500/10 border border-amber-500/30 rounded px-1.5 py-0.5">
+						Beta
+					</span>
+				</a>
+
+				<div className="flex-1 overflow-y-auto px-5 py-4 space-y-6">
+					<div className="text-xs text-muted-foreground leading-relaxed space-y-2">
+						<p>
+							Page Agent Hub lets local apps (e.g. MCP servers) control the Page Agent extension via
+							WebSocket.
+						</p>
+						<p>
+							Check out the official{' '}
+							<a
+								href="https://github.com/alibaba/page-agent/tree/main/packages/mcp"
+								target="_blank"
+								rel="noopener noreferrer"
+								className="underline hover:text-foreground"
+							>
+								MCP server package
+							</a>
+							.
+						</p>
+					</div>
+
+					<HubConfig />
+
+					<ProtocolDocsCollapsible />
+				</div>
+
+				<div className="border-t px-5 py-3 text-[10px] text-muted-foreground/60 flex items-center justify-between">
+					<span className="font-mono">v{__VERSION__}</span>
+					<span>
+						Built with ♥️ by{' '}
+						<a
+							href="https://github.com/gaomeng1900"
+							target="_blank"
+							rel="noopener noreferrer"
+							className="underline hover:text-foreground"
+						>
+							@Simon
+						</a>
+					</span>
+				</div>
+			</aside>
+
+			{/* Right — Live session */}
+			<main className="flex-1 flex flex-col min-w-0 relative">
+				<MotionOverlay active={isRunning} />
+
+				<header className="flex items-center justify-between border-b px-5 h-12">
+					<div className="flex items-center gap-2 text-xs text-muted-foreground">
+						<WsIcon className="size-3.5" />
+						<span>{wsLabel}</span>
+					</div>
+					<div className="flex items-center gap-3">
+						<StatusDot status={status} />
+						{isRunning && (
+							<Button variant="destructive" size="sm" onClick={stop} className="h-7 text-xs">
+								<Square className="size-3 mr-1" />
+								Stop
+							</Button>
+						)}
+					</div>
+				</header>
+
+				{/* Task banner */}
+				{currentTask && (
+					<div className="border-b px-5 py-2 bg-muted/30">
+						<div className="text-[10px] text-muted-foreground uppercase tracking-wide">
+							Current Task
+						</div>
+						<div className="text-sm font-medium truncate" title={currentTask}>
+							{currentTask}
+						</div>
+					</div>
+				)}
+
+				{/* Event stream */}
+				<div ref={historyRef} className="flex-1 overflow-y-auto p-5 space-y-2">
+					{!currentTask && history.length === 0 && !isRunning && (
+						<div className="flex flex-col items-center justify-center h-full text-muted-foreground gap-3">
+							<WsIcon className="size-10 opacity-30" />
+							<p className="text-sm">
+								{wsState === 'connected'
+									? 'Waiting for task from external caller…'
+									: 'No active session'}
+							</p>
+						</div>
+					)}
+
+					{history.map((event, index) => (
+						<EventCard key={index} event={event} />
+					))}
+
+					{activity && <ActivityCard activity={activity} />}
+				</div>
+			</main>
+		</div>
+	)
+}
+
+function HubConfig() {
+	const [allowAll, setAllowAll] = useState(false)
+
+	useEffect(() => {
+		chrome.storage.local.get('allowAllHubConnection').then((r) => {
+			setAllowAll(r.allowAllHubConnection === true)
+		})
+	}, [])
+
+	const toggle = (checked: boolean) => {
+		setAllowAll(checked)
+		chrome.storage.local.set({ allowAllHubConnection: checked })
+	}
+
+	return (
+		<div>
+			<h3 className="text-[11px] font-semibold text-foreground/80 uppercase tracking-wider mb-2">
+				Config
+			</h3>
+			<div className="group/hub relative">
+				<label
+					className={`flex items-center justify-between p-3 rounded-md border cursor-pointer text-xs ${allowAll ? 'bg-amber-500/10 border-amber-500/30 text-amber-600' : 'bg-muted/50 text-muted-foreground'}`}
+				>
+					Auto-approve connections
+					<Switch
+						checked={allowAll}
+						onCheckedChange={toggle}
+						className={allowAll ? 'data-[state=checked]:bg-amber-500' : ''}
+					/>
+				</label>
+
+				{/* hide with invisible absolute opacity-0*/}
+				<div className="group-hover/hub:visible group-hover/hub:opacity-100 transition-opacity duration-150  left-0 right-0 top-full z-10 pt-2">
+					<div className="relative p-2.5 rounded-md border border-border bg-background/60 backdrop-blur-md shadow-2xl text-muted-foreground text-xs leading-relaxed">
+						<div className="absolute -top-1.5 left-5 size-3 rotate-45 rounded-[1px] border-l border-t border-border bg-background/60 backdrop-blur-md" />
+						By default, each connection requires your approval before running tasks. <br />
+						Enable this to skip per-session approval.
+						<br />
+						<span className="font-semibold">* Use with caution!</span>
+					</div>
+				</div>
+			</div>
+		</div>
+	)
+}
+
+function ProtocolDocsCollapsible() {
+	const [open, setOpen] = useState(false)
+
+	return (
+		<div>
+			<button
+				type="button"
+				onClick={() => setOpen(!open)}
+				className="flex items-center gap-1 text-[11px] font-semibold text-foreground/80 uppercase tracking-wider cursor-pointer"
+			>
+				Docs
+				{open ? <FoldVertical className="size-3" /> : <UnfoldVertical className="size-3" />}
+			</button>
+
+			{open && (
+				<div className="mt-3 space-y-4 text-xs text-muted-foreground">
+					<p className="text-[10px]">
+						Connect via <code className="text-[10px]">hub.html?ws=PORT</code>
+					</p>
+
+					<section>
+						<h4 className="text-[11px] font-medium text-foreground/60 mb-1.5">Flow</h4>
+						<ol className="list-decimal list-inside space-y-1 text-[11px] leading-relaxed">
+							<li>Hub opens WS to caller's server</li>
+							<li>
+								Sends <code className="text-[10px]">ready</code>
+							</li>
+							<li>
+								Caller sends <code className="text-[10px]">execute</code> with task
+							</li>
+							<li>Hub runs agent, streams events</li>
+							<li>
+								Hub sends <code className="text-[10px]">result</code> or{' '}
+								<code className="text-[10px]">error</code>
+							</li>
+						</ol>
+					</section>
+
+					<section>
+						<h4 className="text-[11px] font-medium text-foreground/60 mb-1.5">Caller → Hub</h4>
+						<pre className="bg-muted/50 rounded-md p-3 font-mono text-[10px] leading-relaxed whitespace-pre-wrap">
+							{`{ type: "execute", task: string, config?: object }
+{ type: "stop" }`}
+						</pre>
+					</section>
+
+					<section>
+						<h4 className="text-[11px] font-medium text-foreground/60 mb-1.5">Hub → Caller</h4>
+						<pre className="bg-muted/50 rounded-md p-3 font-mono text-[10px] leading-relaxed whitespace-pre-wrap">
+							{`{ type: "ready" }
+{ type: "result", success: boolean, data: string }
+{ type: "error", message: string }`}
+						</pre>
+					</section>
+				</div>
+			)}
+		</div>
+	)
+}
diff --git a/packages/extension/src/entrypoints/hub/hub-ws.ts b/packages/extension/src/entrypoints/hub/hub-ws.ts
new file mode 100644
index 0000000..c439d28
--- /dev/null
+++ b/packages/extension/src/entrypoints/hub/hub-ws.ts
@@ -0,0 +1,243 @@
+/**
+ * Hub WebSocket Protocol
+ *
+ * Hub connects as WS client to `ws://localhost:{port}`.
+ * All messages are JSON. One task at a time.
+ *
+ * Inbound (Caller → Hub):
+ *   { type: "execute", task: string, config?: object }
+ *   { type: "stop" }
+ *
+ * Outbound (Hub → Caller):
+ *   { type: "ready" }
+ *   { type: "result", success: boolean, data: string }
+ *   { type: "error", message: string }
+ */
+import type { ExecutionResult } from '@page-agent/core'
+import { useEffect, useRef, useState } from 'react'
+
+import type { ExtConfig } from '@/agent/useAgent'
+
+// --- Protocol types ---
+
+interface ExecuteMessage {
+	type: 'execute'
+	task: string
+	config?: Record<string, unknown>
+}
+
+interface StopMessage {
+	type: 'stop'
+}
+
+type InboundMessage = ExecuteMessage | StopMessage
+
+interface ReadyMessage {
+	type: 'ready'
+}
+
+interface ResultMessage {
+	type: 'result'
+	success: boolean
+	data: string
+}
+
+interface ErrorMessage {
+	type: 'error'
+	message: string
+}
+
+type OutboundMessage = ReadyMessage | ResultMessage | ErrorMessage
+
+export type HubWsState = 'connecting' | 'connected' | 'disconnected'
+
+// --- HubWs class ---
+
+export interface HubWsHandlers {
+	onExecute: (
+		task: string,
+		config?: Record<string, unknown>
+	) => Promise<{ success: boolean; data: string }>
+	onStop: () => void
+}
+
+/**
+ * Framework-agnostic WebSocket client for Hub.
+ * Connects to an external WS server, receives tasks, dispatches to handlers,
+ * and sends results back. No React, no DOM.
+ */
+export class HubWs {
+	#ws: WebSocket | null = null
+	#state: HubWsState = 'disconnected'
+	#busy = false
+	#approved = false
+	#handlers: HubWsHandlers
+	#port: number
+	#onStateChange: (state: HubWsState) => void
+
+	constructor(port: number, handlers: HubWsHandlers, onStateChange: (state: HubWsState) => void) {
+		this.#port = port
+		this.#handlers = handlers
+		this.#onStateChange = onStateChange
+	}
+
+	get state() {
+		return this.#state
+	}
+
+	get busy() {
+		return this.#busy
+	}
+
+	connect() {
+		if (this.#ws) return
+		this.#setState('connecting')
+
+		const ws = new WebSocket(`ws://localhost:${this.#port}`)
+		this.#ws = ws
+
+		ws.addEventListener('open', () => {
+			this.#setState('connected')
+			this.#send({ type: 'ready' })
+		})
+
+		ws.addEventListener('close', () => {
+			this.#ws = null
+			this.#busy = false
+			this.#approved = false
+			this.#setState('disconnected')
+		})
+
+		ws.addEventListener('message', (event) => {
+			this.#handleMessage(event.data as string)
+		})
+	}
+
+	disconnect() {
+		this.#ws?.close()
+		this.#ws = null
+		this.#busy = false
+		this.#approved = false
+		this.#setState('disconnected')
+	}
+
+	#setState(state: HubWsState) {
+		if (this.#state === state) return
+		this.#state = state
+		this.#onStateChange(state)
+	}
+
+	#send(msg: OutboundMessage) {
+		if (this.#ws?.readyState === WebSocket.OPEN) {
+			this.#ws.send(JSON.stringify(msg))
+		}
+	}
+
+	async #handleMessage(raw: string) {
+		let msg: InboundMessage
+		try {
+			msg = JSON.parse(raw)
+		} catch {
+			return
+		}
+
+		if (!(await this.#checkApproval())) {
+			this.#send({ type: 'error', message: 'User denied the connection request.' })
+			return
+		}
+
+		switch (msg.type) {
+			case 'execute':
+				this.#handleExecute(msg)
+				break
+			case 'stop':
+				this.#handlers.onStop()
+				break
+		}
+	}
+
+	async #checkApproval(): Promise<boolean> {
+		if (this.#approved) return true
+
+		const { allowAllHubConnection } = await chrome.storage.local.get('allowAllHubConnection')
+		if (allowAllHubConnection === true) {
+			this.#approved = true
+			return true
+		}
+
+		const ok = window.confirm(
+			'An external application is requesting to control your browser via Page Agent Ext.\nAllow this session?'
+		)
+		if (ok) this.#approved = true
+		return ok
+	}
+
+	async #handleExecute(msg: ExecuteMessage) {
+		if (this.#busy) {
+			this.#send({ type: 'error', message: 'Hub is busy with another task' })
+			return
+		}
+
+		this.#busy = true
+		try {
+			const result = await this.#handlers.onExecute(msg.task, msg.config)
+			this.#send({ type: 'result', success: result.success, data: result.data })
+		} catch (err) {
+			this.#send({ type: 'error', message: err instanceof Error ? err.message : String(err) })
+		} finally {
+			this.#busy = false
+		}
+	}
+}
+
+// --- React hook ---
+
+/**
+ * React hook that bridges HubWs to the agent's execute/stop/configure.
+ * Handles the config-before-execute dance internally.
+ */
+export function useHubWs(
+	execute: (task: string) => Promise<ExecutionResult>,
+	stop: () => void,
+	configure: (config: ExtConfig) => Promise<void>,
+	config: ExtConfig | null
+): { wsState: HubWsState } {
+	const wsPort = new URLSearchParams(location.search).get('ws')
+	const [wsState, setWsState] = useState<HubWsState>(() => (wsPort ? 'connecting' : 'disconnected'))
+	const hubWsRef = useRef<HubWs | null>(null)
+
+	const latestRef = useRef({ execute, stop, configure, config })
+	useEffect(() => {
+		latestRef.current = { execute, stop, configure, config }
+	})
+
+	useEffect(() => {
+		if (!wsPort) return
+
+		const hubWs = new HubWs(
+			Number(wsPort),
+			{
+				onExecute: async (task, incomingConfig) => {
+					const { execute, configure, config } = latestRef.current
+					if (incomingConfig) {
+						await configure({ ...config, ...incomingConfig } as ExtConfig)
+					}
+					const result = await execute(task)
+					return { success: result.success, data: result.data }
+				},
+				onStop: () => latestRef.current.stop(),
+			},
+			setWsState
+		)
+
+		hubWs.connect()
+		hubWsRef.current = hubWs
+
+		return () => {
+			hubWs.disconnect()
+			hubWsRef.current = null
+		}
+	}, [wsPort])
+
+	return { wsState }
+}
diff --git a/packages/extension/src/entrypoints/hub/index.html b/packages/extension/src/entrypoints/hub/index.html
new file mode 100644
index 0000000..d564cb0
--- /dev/null
+++ b/packages/extension/src/entrypoints/hub/index.html
@@ -0,0 +1,13 @@
+<!doctype html>
+<html>
+	<head>
+		<meta charset="UTF-8" />
+		<meta name="viewport" content="width=device-width, initial-scale=1.0" />
+		<link rel="icon" type="image/png" href="/assets/page-agent-64.png" />
+		<title>Page Agent Hub</title>
+	</head>
+	<body>
+		<div id="root"></div>
+		<script type="module" src="./main.tsx"></script>
+	</body>
+</html>
diff --git a/packages/extension/src/entrypoints/hub/main.tsx b/packages/extension/src/entrypoints/hub/main.tsx
new file mode 100644
index 0000000..05504da
--- /dev/null
+++ b/packages/extension/src/entrypoints/hub/main.tsx
@@ -0,0 +1,25 @@
+import React from 'react'
+import ReactDOM from 'react-dom/client'
+
+import { ErrorBoundary } from '@/components/ErrorBoundary'
+
+import App from './App'
+
+import '@/assets/index.css'
+
+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>
+			<App />
+		</ErrorBoundary>
+	</React.StrictMode>
+)
diff --git a/packages/extension/src/entrypoints/main-world.ts b/packages/extension/src/entrypoints/main-world.ts
new file mode 100644
index 0000000..61973e9
--- /dev/null
+++ b/packages/extension/src/entrypoints/main-world.ts
@@ -0,0 +1,131 @@
+import type { AgentActivity, AgentStatus, ExecutionResult, HistoricalEvent } from '@page-agent/core'
+
+export type Execute = (task: string, config: ExecuteConfig) => Promise<ExecutionResult>
+
+export interface ExecuteConfig {
+	baseURL: string
+	model: string
+	apiKey?: string
+
+	/**
+	 * Global system-level instructions for the agent.
+	 * Equivalent to `AgentConfig.instructions.system`.
+	 */
+	systemInstruction?: string
+
+	/**
+	 * Whether to include the initial tab (that holds this main world script) in the task.
+	 * @default true
+	 */
+	includeInitialTab?: boolean
+
+	/** Control all unpinned tabs in the window instead of only the tab group. */
+	experimentalIncludeAllTabs?: boolean
+
+	onStatusChange?: (status: AgentStatus) => void
+	onActivity?: (activity: AgentActivity) => void
+	onHistoryUpdate?: (history: HistoricalEvent[]) => void
+}
+
+export default defineUnlistedScript(() => {
+	let _lastId = 0
+	function getId() {
+		_lastId += 1
+		return _lastId
+	}
+
+	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 (!config) throw new Error('Config is required')
+		if (!config.baseURL) throw new Error('Config must have a baseURL')
+		if (!config.model) throw new Error('Config must have a model')
+
+		const id = getId()
+
+		const promise = new Promise<ExecutionResult>((resolve, reject) => {
+			function handleMessage(e: MessageEvent) {
+				if (e.source !== window) return
+
+				const data = e.data
+				if (typeof data !== 'object' || data === null) return
+				if (data.channel !== 'PAGE_AGENT_EXT_RESPONSE') 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) {
+					reject(new Error(data.error))
+				} else {
+					resolve(data.payload)
+				}
+			}
+
+			// @note will be removed on dispose or result
+			window.addEventListener('message', handleMessage)
+		})
+
+		window.postMessage(
+			{
+				channel: 'PAGE_AGENT_EXT_REQUEST',
+				id,
+				action: 'execute',
+				payload: {
+					task,
+					config: {
+						baseURL: config.baseURL,
+						model: config.model,
+						apiKey: config.apiKey,
+						systemInstruction: config.systemInstruction,
+						includeInitialTab: config.includeInitialTab,
+						experimentalIncludeAllTabs: config.experimentalIncludeAllTabs,
+					},
+				},
+			},
+			'*'
+		)
+
+		return promise
+	}
+
+	const stop = () => {
+		const id = getId()
+
+		window.postMessage(
+			{
+				channel: 'PAGE_AGENT_EXT_REQUEST',
+				id,
+				action: 'stop',
+			},
+			'*'
+		)
+	}
+
+	;(window as any).PAGE_AGENT_EXT_VERSION = __VERSION__
+	;(window as any).PAGE_AGENT_EXT = {
+		version: __VERSION__,
+		execute,
+		stop,
+	}
+})
diff --git a/packages/extension/src/entrypoints/sidepanel/App.tsx b/packages/extension/src/entrypoints/sidepanel/App.tsx
new file mode 100644
index 0000000..e54948f
--- /dev/null
+++ b/packages/extension/src/entrypoints/sidepanel/App.tsx
@@ -0,0 +1,235 @@
+import { History, Send, Settings, Square } from 'lucide-react'
+import { useCallback, useEffect, useRef, useState } from 'react'
+
+import { ConfigPanel } from '@/components/ConfigPanel'
+import { HistoryDetail } from '@/components/HistoryDetail'
+import { HistoryList } from '@/components/HistoryList'
+import { ActivityCard, EventCard } from '@/components/cards'
+import { EmptyState, Logo, MotionOverlay, StatusDot } from '@/components/misc'
+import { Button } from '@/components/ui/button'
+import {
+	InputGroup,
+	InputGroupAddon,
+	InputGroupButton,
+	InputGroupTextarea,
+} from '@/components/ui/input-group'
+import { saveSession } from '@/lib/db'
+
+import { useAgent } from '../../agent/useAgent'
+
+type View =
+	| { name: 'chat' }
+	| { name: 'config' }
+	| { name: 'history' }
+	| { name: 'history-detail'; sessionId: string }
+
+export default function App() {
+	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' || status === 'stopped') &&
+			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) {
+			historyRef.current.scrollTop = historyRef.current.scrollHeight
+		}
+	}, [history, activity])
+
+	const runTask = useCallback(
+		(task: string) => {
+			const normalizedTask = task.trim()
+			if (!normalizedTask || status === 'running') return
+
+			setInputValue('')
+			setView({ name: 'chat' })
+
+			execute(normalizedTask).catch((error) => {
+				console.error('[SidePanel] Failed to execute task:', error)
+			})
+		},
+		[execute, status]
+	)
+
+	const handleSubmit = useCallback(
+		(e?: React.SyntheticEvent) => {
+			e?.preventDefault()
+			runTask(inputValue)
+		},
+		[inputValue, runTask]
+	)
+
+	const handleStop = useCallback(() => {
+		console.log('[SidePanel] Stopping task...')
+		stop()
+	}, [stop])
+
+	const handleKeyDown = (e: React.KeyboardEvent) => {
+		if (e.key === 'Enter' && !e.shiftKey && !e.nativeEvent.isComposing) {
+			e.preventDefault()
+			handleSubmit()
+		}
+	}
+
+	// --- View routing ---
+
+	if (view.name === 'config') {
+		return (
+			<ConfigPanel
+				config={config}
+				onSave={async (newConfig) => {
+					await configure(newConfig)
+					setView({ name: 'chat' })
+				}}
+				onClose={() => setView({ name: 'chat' })}
+			/>
+		)
+	}
+
+	if (view.name === 'history') {
+		return (
+			<HistoryList
+				onSelect={(id) => setView({ name: 'history-detail', sessionId: id })}
+				onBack={() => setView({ name: 'chat' })}
+				onRerun={runTask}
+			/>
+		)
+	}
+
+	if (view.name === 'history-detail') {
+		return (
+			<HistoryDetail
+				sessionId={view.sessionId}
+				onBack={() => setView({ name: 'history' })}
+				onRerun={runTask}
+			/>
+		)
+	}
+
+	// --- Chat view ---
+
+	const isRunning = status === 'running'
+	const showEmptyState = !currentTask && history.length === 0 && !isRunning
+
+	return (
+		<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-1">
+					<StatusDot status={status} />
+					<Button
+						variant="ghost"
+						size="icon-sm"
+						onClick={() => setView({ name: 'history' })}
+						className="cursor-pointer"
+						aria-label="History"
+						title="History"
+					>
+						<History className="size-3.5" />
+					</Button>
+					<Button
+						variant="ghost"
+						size="icon-sm"
+						onClick={() => setView({ name: 'config' })}
+						className="cursor-pointer"
+						aria-label="Settings"
+						title="Settings"
+					>
+						<Settings className="size-3.5" />
+					</Button>
+				</div>
+			</header>
+
+			{/* Content */}
+			<main className="flex-1 overflow-hidden flex flex-col">
+				{/* Current task */}
+				{currentTask && (
+					<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 truncate" title={currentTask}>
+							{currentTask}
+						</div>
+					</div>
+				)}
+
+				{/* History */}
+				<div ref={historyRef} className="flex-1 overflow-y-auto p-3 space-y-2">
+					{showEmptyState && <EmptyState />}
+
+					{history.map((event, index) => (
+						<EventCard key={index} event={event} />
+					))}
+
+					{/* Activity indicator at bottom */}
+					{activity && <ActivityCard activity={activity} />}
+				</div>
+			</main>
+
+			{/* Input */}
+			<footer className="border-t p-3">
+				<InputGroup className="relative rounded-lg">
+					<InputGroupTextarea
+						ref={textareaRef}
+						placeholder="Describe your task... (Enter to send)"
+						value={inputValue}
+						onChange={(e) => setInputValue(e.target.value)}
+						onKeyDown={handleKeyDown}
+						disabled={isRunning}
+						className="text-xs pr-12 min-h-10"
+					/>
+					<InputGroupAddon align="inline-end" className="absolute bottom-0 right-0">
+						{isRunning ? (
+							<InputGroupButton
+								size="icon-sm"
+								variant="destructive"
+								onClick={handleStop}
+								className="size-7"
+								aria-label="Stop task"
+								title="Stop task"
+							>
+								<Square className="size-3" />
+							</InputGroupButton>
+						) : (
+							<InputGroupButton
+								size="icon-sm"
+								variant="default"
+								onClick={() => handleSubmit()}
+								disabled={!inputValue.trim()}
+								className="size-7 cursor-pointer"
+								aria-label="Send"
+								title="Send"
+							>
+								<Send className="size-3" />
+							</InputGroupButton>
+						)}
+					</InputGroupAddon>
+				</InputGroup>
+			</footer>
+		</div>
+	)
+}
diff --git a/packages/extension/src/entrypoints/sidepanel/index.html b/packages/extension/src/entrypoints/sidepanel/index.html
new file mode 100644
index 0000000..703e8c8
--- /dev/null
+++ b/packages/extension/src/entrypoints/sidepanel/index.html
@@ -0,0 +1,13 @@
+<!doctype html>
+<html>
+	<head>
+		<meta charset="UTF-8" />
+		<meta name="viewport" content="width=device-width, initial-scale=1.0" />
+		<link rel="icon" type="image/png" href="/assets/page-agent-64.png" />
+		<title>Page Agent</title>
+	</head>
+	<body>
+		<div id="root"></div>
+		<script type="module" src="./main.tsx"></script>
+	</body>
+</html>
diff --git a/packages/extension/src/entrypoints/sidepanel/main.tsx b/packages/extension/src/entrypoints/sidepanel/main.tsx
new file mode 100644
index 0000000..05f158b
--- /dev/null
+++ b/packages/extension/src/entrypoints/sidepanel/main.tsx
@@ -0,0 +1,26 @@
+import React from 'react'
+import ReactDOM from 'react-dom/client'
+
+import { ErrorBoundary } from '@/components/ErrorBoundary'
+
+import App from './App'
+
+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>
+			<App />
+		</ErrorBoundary>
+	</React.StrictMode>
+)
diff --git a/packages/extension/src/lib/db.ts b/packages/extension/src/lib/db.ts
new file mode 100644
index 0000000..e0db44c
--- /dev/null
+++ b/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' | 'stopped'
+	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')
+}
diff --git a/packages/extension/src/lib/history-export.ts b/packages/extension/src/lib/history-export.ts
new file mode 100644
index 0000000..83e6ab5
--- /dev/null
+++ b/packages/extension/src/lib/history-export.ts
@@ -0,0 +1,60 @@
+import type { HistoricalEvent } from '@page-agent/core'
+
+const EXPORT_FILE_PREFIX = 'page-agent-history'
+const MAX_TASK_SLUG_LENGTH = 40
+
+export function serializeHistoryExport(history: HistoricalEvent[]): string {
+	return `${JSON.stringify(history, null, 2)}\n`
+}
+
+export function buildHistoryExportFilename(task: string, createdAt: number): string {
+	const taskSlug = sanitizeTaskForFilename(task)
+	const timestamp = formatTimestampForFilename(createdAt)
+
+	return taskSlug
+		? `${EXPORT_FILE_PREFIX}-${taskSlug}-${timestamp}.json`
+		: `${EXPORT_FILE_PREFIX}-${timestamp}.json`
+}
+
+export function downloadHistoryExport(
+	task: string,
+	createdAt: number,
+	history: HistoricalEvent[]
+): void {
+	const filename = buildHistoryExportFilename(task, createdAt)
+	const content = serializeHistoryExport(history)
+	const blob = new Blob([content], { type: 'application/json;charset=utf-8' })
+	const url = URL.createObjectURL(blob)
+	const link = document.createElement('a')
+
+	link.href = url
+	link.download = filename
+	link.click()
+
+	URL.revokeObjectURL(url)
+}
+
+function sanitizeTaskForFilename(task: string): string {
+	return task
+		.trim()
+		.toLowerCase()
+		.replace(/[^a-z0-9]+/g, '-')
+		.replace(/^-+|-+$/g, '')
+		.slice(0, MAX_TASK_SLUG_LENGTH)
+}
+
+function formatTimestampForFilename(createdAt: number): string {
+	const date = new Date(createdAt)
+	const year = date.getFullYear()
+	const month = pad(date.getMonth() + 1)
+	const day = pad(date.getDate())
+	const hours = pad(date.getHours())
+	const minutes = pad(date.getMinutes())
+	const seconds = pad(date.getSeconds())
+
+	return `${year}-${month}-${day}_${hours}-${minutes}-${seconds}`
+}
+
+function pad(value: number): string {
+	return value.toString().padStart(2, '0')
+}
diff --git a/packages/extension/src/lib/utils.ts b/packages/extension/src/lib/utils.ts
new file mode 100644
index 0000000..c15e7f7
--- /dev/null
+++ b/packages/extension/src/lib/utils.ts
@@ -0,0 +1,6 @@
+import { type ClassValue, clsx } from 'clsx'
+import { twMerge } from 'tailwind-merge'
+
+export function cn(...inputs: ClassValue[]) {
+	return twMerge(clsx(inputs))
+}
diff --git a/packages/extension/src/types/assets.d.ts b/packages/extension/src/types/assets.d.ts
new file mode 100644
index 0000000..1c0c794
--- /dev/null
+++ b/packages/extension/src/types/assets.d.ts
@@ -0,0 +1,25 @@
+// Asset type declarations
+declare module '*.webp' {
+	const src: string
+	export default src
+}
+
+declare module '*.png' {
+	const src: string
+	export default src
+}
+
+declare module '*.jpg' {
+	const src: string
+	export default src
+}
+
+declare module '*.jpeg' {
+	const src: string
+	export default src
+}
+
+declare module '*.svg' {
+	const src: string
+	export default src
+}
diff --git a/packages/extension/src/types/globals.d.ts b/packages/extension/src/types/globals.d.ts
new file mode 100644
index 0000000..4160217
--- /dev/null
+++ b/packages/extension/src/types/globals.d.ts
@@ -0,0 +1 @@
+declare const __VERSION__: string
diff --git a/packages/extension/src/types/markdown.d.ts b/packages/extension/src/types/markdown.d.ts
new file mode 100644
index 0000000..6710f5c
--- /dev/null
+++ b/packages/extension/src/types/markdown.d.ts
@@ -0,0 +1,4 @@
+declare module '*.md?raw' {
+	const content: string
+	export default content
+}
diff --git a/packages/extension/tsconfig.json b/packages/extension/tsconfig.json
new file mode 100644
index 0000000..04d525d
--- /dev/null
+++ b/packages/extension/tsconfig.json
@@ -0,0 +1,13 @@
+{
+    "extends": "./.wxt/tsconfig.json",
+    "compilerOptions": {
+        "tsBuildInfoFile": "./node_modules/.tmp/tsconfig.tsbuildinfo",
+        "useDefineForClassFields": true,
+        "strictNullChecks": true,
+        "jsx": "react-jsx",
+        "types": ["node", "chrome"],
+        "paths": {
+            "@/*": ["./src/*"]
+        }
+    }
+}
diff --git a/packages/extension/wxt.config.js b/packages/extension/wxt.config.js
new file mode 100644
index 0000000..2f29be0
--- /dev/null
+++ b/packages/extension/wxt.config.js
@@ -0,0 +1,69 @@
+import tailwindcss from '@tailwindcss/vite'
+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',
+	modules: ['@wxt-dev/module-react'],
+	webExt: {
+		chromiumProfile: chromeProfile,
+		keepProfileChanges: true,
+		chromiumArgs: ['--hide-crash-restore-bubble'],
+	},
+	vite: () => ({
+		plugins: [tailwindcss()],
+		define: {
+			__VERSION__: JSON.stringify(pkg.version),
+		},
+		optimizeDeps: {
+			force: true,
+		},
+		build: {
+			minify: false,
+			chunkSizeWarningLimit: 2000,
+			cssCodeSplit: true,
+			rollupOptions: {
+				onwarn: function (message, handler) {
+					if (message.code === 'EVAL') return
+					handler(message)
+				},
+			},
+		},
+	}),
+	zip: {
+		artifactTemplate: 'page-agent-ext-{{version}}-{{browser}}.zip',
+	},
+	manifest: {
+		key: 'MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAqbzT0iTYeYlnCvDJIGDnGU8oarJgZILDzSfLi/ufuSxXEPDKuMyD892GhvrMCZNVHS11Sh6NYUOc/PcUOhtaR2urHtcNkrpSJNV10zUamY7fxBdVEkOucfyLu8INVy+teis62MoRWYPaUPkfZUjrLGW8MsZ9aFzARfu9GGDEp2EAYsWDN6w6vyz9LJ82pm542EWnVT4MjmDPgvYFCWGBtaU/dfHD+GAX6URJFapsCvryVURKJ+76c/GO9/I3EX1IBfbY6dec78bLCMvVxiTmiv36KyGPwX1OpakW8IiCpXWdbAxjm+plbYlp5t5zTyyoE3sOSFeXsBH0Kg27o8GcvQIDAQAB',
+		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>'],
+		icons: {
+			64: 'assets/page-agent-64.png',
+		},
+		action: {
+			default_title: '__MSG_extActionTitle__',
+		},
+		web_accessible_resources: [
+			{
+				resources: ['main-world.js'],
+				matches: ['*://*/*'],
+			},
+		],
+		side_panel: {
+			default_path: 'sidepanel/index.html',
+		},
+		externally_connectable: {
+			matches: ['http://localhost/*'],
+		},
+	},
+})
diff --git a/packages/llms/package.json b/packages/llms/package.json
new file mode 100644
index 0000000..3f24842
--- /dev/null
+++ b/packages/llms/package.json
@@ -0,0 +1,60 @@
+{
+    "name": "@page-agent/llms",
+    "version": "1.12.1",
+    "type": "module",
+    "main": "./src/index.ts",
+    "types": "./src/index.ts",
+    "exports": {
+        ".": {
+            "types": "./src/index.ts",
+            "default": "./src/index.ts"
+        }
+    },
+    "publishConfig": {
+        "main": "./dist/lib/page-agent-llms.js",
+        "module": "./dist/lib/page-agent-llms.js",
+        "types": "./dist/lib/index.d.ts",
+        "exports": {
+            ".": {
+                "types": "./dist/lib/index.d.ts",
+                "import": "./dist/lib/page-agent-llms.js",
+                "default": "./dist/lib/page-agent-llms.js"
+            }
+        }
+    },
+    "files": [
+        "dist/"
+    ],
+    "description": "LLM client with reflection-before-action mental model for page-agent",
+    "keywords": [
+        "page-agent",
+        "llm",
+        "openai",
+        "tool-calling",
+        "agent"
+    ],
+    "author": "Simon<gaomeng1900>",
+    "license": "MIT",
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/alibaba/page-agent.git",
+        "directory": "packages/llms"
+    },
+    "homepage": "https://alibaba.github.io/page-agent/",
+    "scripts": {
+        "build": "vite build",
+        "test": "vitest run --project llms",
+        "test:live": "vitest run --project llms:live",
+        "prepublishOnly": "node ../../scripts/pre-publish.js",
+        "postpublish": "node ../../scripts/post-publish.js"
+    },
+    "dependencies": {
+        "chalk": "^5.6.2"
+    },
+    "peerDependencies": {
+        "zod": "^3.25.0 || ^4.0.0"
+    },
+    "devDependencies": {
+        "zod": "^4.4.3"
+    }
+}
diff --git a/packages/llms/src/OpenAIClient.test.ts b/packages/llms/src/OpenAIClient.test.ts
new file mode 100644
index 0000000..527d51e
--- /dev/null
+++ b/packages/llms/src/OpenAIClient.test.ts
@@ -0,0 +1,369 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import * as z from 'zod/v4'
+
+import { OpenAIClient } from './OpenAIClient'
+import { InvokeError, InvokeErrorTypes } from './errors'
+import { parseLLMConfig } from './index'
+import type { LLMConfig, Tool } from './types'
+
+// ---------- Fixtures ----------
+
+function makeClient(overrides: Partial<LLMConfig> = {}) {
+	const fetchMock = vi.fn<typeof fetch>()
+	const config = parseLLMConfig({
+		baseURL: 'http://test.local/v1',
+		model: 'test-model',
+		apiKey: 'sk-test',
+		customFetch: fetchMock,
+		...overrides,
+	})
+	const client = new OpenAIClient(config)
+	return { client, fetchMock }
+}
+
+function makeTool(): Tool<{ name: string }, string> {
+	return {
+		description: 'greet',
+		inputSchema: z.object({ name: z.string() }),
+		execute: vi.fn(async (args) => `hello ${args.name}`),
+	}
+}
+
+function jsonResponse(body: unknown, status = 200): Response {
+	return new Response(JSON.stringify(body), {
+		status,
+		headers: { 'Content-Type': 'application/json' },
+	})
+}
+
+function toolCallBody(toolName: string, args: unknown, finishReason = 'tool_calls') {
+	return {
+		choices: [
+			{
+				finish_reason: finishReason,
+				message: {
+					tool_calls: [
+						{
+							id: 'call_1',
+							type: 'function',
+							function: {
+								name: toolName,
+								arguments: typeof args === 'string' ? args : JSON.stringify(args),
+							},
+						},
+					],
+				},
+			},
+		],
+		usage: { prompt_tokens: 10, completion_tokens: 5, total_tokens: 15 },
+	}
+}
+
+function abortError(message = 'aborted'): Error {
+	const err = new Error(message)
+	err.name = 'AbortError'
+	return err
+}
+
+function getSentBody(fetchMock: ReturnType<typeof vi.fn>): Record<string, unknown> {
+	const init = fetchMock.mock.calls[0][1] as RequestInit
+	return JSON.parse(init.body as string)
+}
+
+const signal = new AbortController().signal
+
+// ---------- Request construction ----------
+
+describe('OpenAIClient.invoke — request construction', () => {
+	let setup: ReturnType<typeof makeClient>
+	const tools = { greet: makeTool() }
+
+	beforeEach(() => {
+		setup = makeClient()
+		setup.fetchMock.mockResolvedValue(jsonResponse(toolCallBody('greet', { name: 'world' })))
+	})
+
+	it('defaults tool_choice to "required" when no toolChoiceName is given', async () => {
+		await setup.client.invoke([], tools, signal)
+		expect(getSentBody(setup.fetchMock).tool_choice).toBe('required')
+	})
+
+	it('uses named tool_choice when toolChoiceName is given', async () => {
+		await setup.client.invoke([], tools, signal, { toolChoiceName: 'greet' })
+		expect(getSentBody(setup.fetchMock).tool_choice).toEqual({
+			type: 'function',
+			function: { name: 'greet' },
+		})
+	})
+
+	it('falls back to "required" when disableNamedToolChoice is true', async () => {
+		const { client, fetchMock } = makeClient({ disableNamedToolChoice: true })
+		fetchMock.mockResolvedValue(jsonResponse(toolCallBody('greet', { name: 'world' })))
+		await client.invoke([], tools, signal, { toolChoiceName: 'greet' })
+		expect(getSentBody(fetchMock).tool_choice).toBe('required')
+	})
+
+	it('sends Authorization header when apiKey is set', async () => {
+		await setup.client.invoke([], tools, signal)
+		const init = setup.fetchMock.mock.calls[0][1]!
+		expect((init.headers as Record<string, string>).Authorization).toBe('Bearer sk-test')
+	})
+
+	it('omits Authorization header when apiKey is empty', async () => {
+		const { client, fetchMock } = makeClient({ apiKey: '' })
+		fetchMock.mockResolvedValue(jsonResponse(toolCallBody('greet', { name: 'world' })))
+		await client.invoke([], tools, signal)
+		const init = fetchMock.mock.calls[0][1]!
+		expect((init.headers as Record<string, string>).Authorization).toBeUndefined()
+	})
+
+	it('applies transformRequestBody (in-place form, returns undefined)', async () => {
+		const { client, fetchMock } = makeClient({
+			transformRequestBody: (body) => {
+				body.custom_flag = 42
+				return undefined
+			},
+		})
+		fetchMock.mockResolvedValue(jsonResponse(toolCallBody('greet', { name: 'world' })))
+		await client.invoke([], tools, signal)
+		expect(getSentBody(fetchMock).custom_flag).toBe(42)
+	})
+
+	it('applies transformRequestBody (returning a new object)', async () => {
+		const { client, fetchMock } = makeClient({
+			transformRequestBody: () => ({ replaced: true }),
+		})
+		fetchMock.mockResolvedValue(jsonResponse(toolCallBody('greet', { name: 'world' })))
+		await client.invoke([], tools, signal)
+		expect(getSentBody(fetchMock)).toEqual({ replaced: true })
+	})
+
+	it('wraps transformRequestBody throws as CONFIG_ERROR', async () => {
+		const { client } = makeClient({
+			transformRequestBody: () => {
+				throw new Error('bad transform')
+			},
+		})
+		await expect(client.invoke([], tools, signal)).rejects.toMatchObject({
+			name: 'InvokeError',
+			type: InvokeErrorTypes.CONFIG_ERROR,
+		})
+	})
+})
+
+// ---------- Success path ----------
+
+describe('OpenAIClient.invoke — success', () => {
+	it('returns toolCall, toolResult and usage', async () => {
+		const { client, fetchMock } = makeClient()
+		const tool = makeTool()
+		fetchMock.mockResolvedValue(jsonResponse(toolCallBody('greet', { name: 'Alice' })))
+
+		const result = await client.invoke([], { greet: tool }, signal)
+
+		expect(result.toolCall).toEqual({ name: 'greet', args: { name: 'Alice' } })
+		expect(result.toolResult).toBe('hello Alice')
+		expect(result.usage).toEqual({
+			promptTokens: 10,
+			completionTokens: 5,
+			totalTokens: 15,
+			cachedTokens: undefined,
+			reasoningTokens: undefined,
+		})
+		expect(tool.execute).toHaveBeenCalledWith({ name: 'Alice' })
+	})
+
+	it('accepts finish_reason="stop" with tool calls', async () => {
+		const { client, fetchMock } = makeClient()
+		fetchMock.mockResolvedValue(jsonResponse(toolCallBody('greet', { name: 'Bob' }, 'stop')))
+		const result = await client.invoke([], { greet: makeTool() }, signal)
+		expect(result.toolResult).toBe('hello Bob')
+	})
+})
+
+// ---------- HTTP errors ----------
+
+describe('OpenAIClient.invoke — HTTP errors', () => {
+	const tools = { greet: makeTool() }
+
+	it.each([
+		[401, InvokeErrorTypes.AUTH_ERROR],
+		[403, InvokeErrorTypes.AUTH_ERROR],
+		[429, InvokeErrorTypes.RATE_LIMIT],
+		[500, InvokeErrorTypes.SERVER_ERROR],
+		[502, InvokeErrorTypes.SERVER_ERROR],
+		[418, InvokeErrorTypes.UNKNOWN],
+	])('maps status %i to %s', async (status, type) => {
+		const { client, fetchMock } = makeClient()
+		fetchMock.mockResolvedValue(jsonResponse({ error: { message: 'nope' } }, status))
+		await expect(client.invoke([], tools, signal)).rejects.toMatchObject({
+			name: 'InvokeError',
+			type,
+		})
+	})
+
+	it('falls back to statusText when body has no error.message', async () => {
+		const { client, fetchMock } = makeClient()
+		fetchMock.mockResolvedValue(
+			new Response('not json', { status: 500, statusText: 'Internal Boom' })
+		)
+		await expect(client.invoke([], tools, signal)).rejects.toMatchObject({
+			type: InvokeErrorTypes.SERVER_ERROR,
+			message: expect.stringContaining('Internal Boom'),
+		})
+	})
+})
+
+// ---------- Response anomalies ----------
+
+describe('OpenAIClient.invoke — response anomalies', () => {
+	const tools = { greet: makeTool() }
+
+	it('throws CONTEXT_LENGTH on finish_reason="length"', async () => {
+		const { client, fetchMock } = makeClient()
+		fetchMock.mockResolvedValue(
+			jsonResponse({ choices: [{ finish_reason: 'length', message: {} }] })
+		)
+		await expect(client.invoke([], tools, signal)).rejects.toMatchObject({
+			type: InvokeErrorTypes.CONTEXT_LENGTH,
+		})
+	})
+
+	it('throws CONTENT_FILTER on finish_reason="content_filter"', async () => {
+		const { client, fetchMock } = makeClient()
+		fetchMock.mockResolvedValue(
+			jsonResponse({ choices: [{ finish_reason: 'content_filter', message: {} }] })
+		)
+		await expect(client.invoke([], tools, signal)).rejects.toMatchObject({
+			type: InvokeErrorTypes.CONTENT_FILTER,
+		})
+	})
+
+	it('throws INVALID_SCHEMA when there are no choices', async () => {
+		const { client, fetchMock } = makeClient()
+		fetchMock.mockResolvedValue(jsonResponse({}))
+		await expect(client.invoke([], tools, signal)).rejects.toMatchObject({
+			type: InvokeErrorTypes.INVALID_SCHEMA,
+		})
+	})
+
+	it('throws NO_TOOL_CALL when message has no tool_calls', async () => {
+		const { client, fetchMock } = makeClient()
+		fetchMock.mockResolvedValue(
+			jsonResponse({ choices: [{ finish_reason: 'tool_calls', message: {} }] })
+		)
+		await expect(client.invoke([], tools, signal)).rejects.toMatchObject({
+			type: InvokeErrorTypes.NO_TOOL_CALL,
+		})
+	})
+
+	it('throws INVALID_TOOL_ARGS when arguments are not valid JSON', async () => {
+		const { client, fetchMock } = makeClient()
+		fetchMock.mockResolvedValue(jsonResponse(toolCallBody('greet', 'not-json{')))
+		await expect(client.invoke([], tools, signal)).rejects.toMatchObject({
+			type: InvokeErrorTypes.INVALID_TOOL_ARGS,
+			message: expect.stringContaining('JSON'),
+		})
+	})
+
+	it('throws INVALID_TOOL_ARGS when args fail Zod validation', async () => {
+		const { client, fetchMock } = makeClient()
+		// tool expects { name: string }, send { name: 123 }
+		fetchMock.mockResolvedValue(jsonResponse(toolCallBody('greet', { name: 123 })))
+		await expect(client.invoke([], tools, signal)).rejects.toMatchObject({
+			type: InvokeErrorTypes.INVALID_TOOL_ARGS,
+		})
+	})
+
+	it('throws UNKNOWN when model calls a tool that does not exist', async () => {
+		const { client, fetchMock } = makeClient()
+		fetchMock.mockResolvedValue(jsonResponse(toolCallBody('mystery', { name: 'x' })))
+		await expect(client.invoke([], tools, signal)).rejects.toMatchObject({
+			type: InvokeErrorTypes.UNKNOWN,
+			message: expect.stringContaining('mystery'),
+		})
+	})
+
+	it('wraps tool.execute failures as TOOL_EXECUTION_ERROR', async () => {
+		const { client, fetchMock } = makeClient()
+		const tool: Tool<{ name: string }, string> = {
+			inputSchema: z.object({ name: z.string() }),
+			execute: vi.fn(async () => {
+				throw new Error('downstream blew up')
+			}),
+		}
+		fetchMock.mockResolvedValue(jsonResponse(toolCallBody('greet', { name: 'x' })))
+		await expect(client.invoke([], { greet: tool }, signal)).rejects.toMatchObject({
+			type: InvokeErrorTypes.TOOL_EXECUTION_ERROR,
+			message: expect.stringContaining('downstream blew up'),
+		})
+	})
+})
+
+// ---------- Abort handling (the important part) ----------
+
+describe('OpenAIClient.invoke — abort', () => {
+	const tools = { greet: makeTool() }
+
+	it('throws AbortError immediately when signal is already aborted', async () => {
+		const { client, fetchMock } = makeClient()
+		const controller = new AbortController()
+		controller.abort()
+
+		await expect(client.invoke([], tools, controller.signal)).rejects.toMatchObject({
+			name: 'AbortError',
+		})
+		expect(fetchMock).not.toHaveBeenCalled()
+	})
+
+	it('propagates AbortError thrown by fetch (does NOT wrap as NETWORK_ERROR)', async () => {
+		const { client, fetchMock } = makeClient()
+		fetchMock.mockRejectedValue(abortError())
+
+		const err = await client.invoke([], tools, signal).catch((e) => e)
+		expect(err).toBeInstanceOf(Error)
+		expect(err).not.toBeInstanceOf(InvokeError)
+		expect(err.name).toBe('AbortError')
+	})
+
+	it('propagates AbortError thrown by response.json() (does NOT wrap as INVALID_RESPONSE)', async () => {
+		const { client, fetchMock } = makeClient()
+		// Fake Response whose .json() rejects with AbortError mid-read
+		const fakeResponse = {
+			ok: true,
+			status: 200,
+			statusText: 'OK',
+			json: () => Promise.reject(abortError()),
+		} as unknown as Response
+		fetchMock.mockResolvedValue(fakeResponse)
+
+		const err = await client.invoke([], tools, signal).catch((e) => e)
+		expect(err).not.toBeInstanceOf(InvokeError)
+		expect(err.name).toBe('AbortError')
+	})
+
+	it('propagates AbortError thrown by tool.execute (does NOT wrap as TOOL_EXECUTION_ERROR)', async () => {
+		const { client, fetchMock } = makeClient()
+		const tool: Tool<{ name: string }, string> = {
+			inputSchema: z.object({ name: z.string() }),
+			execute: vi.fn(async () => {
+				throw abortError()
+			}),
+		}
+		fetchMock.mockResolvedValue(jsonResponse(toolCallBody('greet', { name: 'x' })))
+
+		const err = await client.invoke([], { greet: tool }, signal).catch((e) => e)
+		expect(err).not.toBeInstanceOf(InvokeError)
+		expect(err.name).toBe('AbortError')
+	})
+
+	// Sanity check: the wrappers we deliberately bypass for AbortError still work for normal errors
+	it('still wraps non-Abort fetch errors as NETWORK_ERROR', async () => {
+		const { client, fetchMock } = makeClient()
+		fetchMock.mockRejectedValue(new TypeError('ECONNREFUSED'))
+		await expect(client.invoke([], tools, signal)).rejects.toMatchObject({
+			name: 'InvokeError',
+			type: InvokeErrorTypes.NETWORK_ERROR,
+		})
+	})
+})
diff --git a/packages/llms/src/OpenAIClient.ts b/packages/llms/src/OpenAIClient.ts
new file mode 100644
index 0000000..ba97466
--- /dev/null
+++ b/packages/llms/src/OpenAIClient.ts
@@ -0,0 +1,269 @@
+/**
+ * OpenAI Client implementation
+ */
+import * as z from 'zod/v4'
+
+import { InvokeError, InvokeErrorTypes } from './errors'
+import type {
+	InvokeOptions,
+	InvokeResult,
+	LLMClient,
+	Message,
+	ResolvedLLMConfig,
+	Tool,
+} from './types'
+import { modelPatch, zodToOpenAITool } from './utils'
+
+/**
+ * Client for OpenAI compatible APIs
+ */
+export class OpenAIClient implements LLMClient {
+	config: ResolvedLLMConfig
+	private fetch: typeof globalThis.fetch
+
+	constructor(config: ResolvedLLMConfig) {
+		this.config = config
+		this.fetch = config.customFetch
+	}
+
+	async invoke(
+		messages: Message[],
+		tools: Record<string, Tool>,
+		abortSignal?: AbortSignal,
+		options?: InvokeOptions
+	): Promise<InvokeResult> {
+		abortSignal?.throwIfAborted()
+
+		// 1. Convert tools to OpenAI format
+		const openaiTools = Object.entries(tools).map(([name, t]) => zodToOpenAITool(name, t))
+
+		// Build request body
+
+		let toolChoice: unknown = 'required'
+		if (options?.toolChoiceName && !this.config.disableNamedToolChoice) {
+			toolChoice = { type: 'function', function: { name: options.toolChoiceName } }
+		}
+
+		const requestBody: Record<string, unknown> = {
+			model: this.config.model,
+			messages,
+			tools: openaiTools,
+			parallel_tool_calls: false,
+			tool_choice: toolChoice,
+		}
+		// Only sent if the caller explicitly set it. Most new models throw if this is set.
+		if (this.config.temperature !== undefined) {
+			requestBody.temperature = this.config.temperature
+		}
+
+		modelPatch(requestBody, this.config.baseURL)
+
+		let transformedBody: Record<string, unknown> | undefined
+		try {
+			transformedBody = this.config.transformRequestBody(requestBody)
+		} catch (error) {
+			throw new InvokeError(
+				InvokeErrorTypes.CONFIG_ERROR,
+				`transformRequestBody failed: ${(error as Error).message}`,
+				error
+			)
+		}
+		const finalRequestBody = transformedBody ?? requestBody
+
+		// 2. Call API
+		let response: Response
+		try {
+			response = await this.fetch(`${this.config.baseURL}/chat/completions`, {
+				method: 'POST',
+				headers: {
+					'Content-Type': 'application/json',
+					...(this.config.apiKey && { Authorization: `Bearer ${this.config.apiKey}` }),
+				},
+				body: JSON.stringify(finalRequestBody),
+				signal: abortSignal,
+			})
+		} catch (error: unknown) {
+			if ((error as any)?.name === 'AbortError') throw error
+			console.error(error)
+			throw new InvokeError(InvokeErrorTypes.NETWORK_ERROR, 'Network request failed', error)
+		}
+
+		// 3. Handle HTTP errors
+		if (!response.ok) {
+			let errorData: any
+			try {
+				errorData = await response.json()
+			} catch (error) {
+				if ((error as any)?.name === 'AbortError') throw error
+			}
+			const errorMessage = errorData?.error?.message || response.statusText
+
+			if (response.status === 401 || response.status === 403) {
+				throw new InvokeError(
+					InvokeErrorTypes.AUTH_ERROR,
+					`Authentication failed: ${errorMessage}`,
+					errorData
+				)
+			}
+			if (response.status === 429) {
+				throw new InvokeError(
+					InvokeErrorTypes.RATE_LIMIT,
+					`Rate limit exceeded: ${errorMessage}`,
+					errorData
+				)
+			}
+			if (response.status >= 500) {
+				throw new InvokeError(
+					InvokeErrorTypes.SERVER_ERROR,
+					`Server error: ${errorMessage}`,
+					errorData
+				)
+			}
+			throw new InvokeError(
+				InvokeErrorTypes.UNKNOWN,
+				`HTTP ${response.status}: ${errorMessage}`,
+				errorData
+			)
+		}
+
+		// 4. Parse and validate response
+		let data: any
+		try {
+			data = await response.json()
+		} catch (error) {
+			if ((error as any)?.name === 'AbortError') throw error
+			throw new InvokeError(
+				InvokeErrorTypes.INVALID_RESPONSE,
+				'Response body is not valid JSON',
+				error
+			)
+		}
+
+		const choice = data.choices?.[0]
+		if (!choice) {
+			throw new InvokeError(InvokeErrorTypes.INVALID_SCHEMA, 'No choices in response', data)
+		}
+
+		// Check finish_reason
+		switch (choice.finish_reason) {
+			case 'tool_calls':
+			case 'function_call': // gemini
+			case 'stop': // some models use this even with tool calls
+				break
+			case 'length':
+				throw new InvokeError(
+					InvokeErrorTypes.CONTEXT_LENGTH,
+					'Response truncated: max tokens reached',
+					undefined,
+					data
+				)
+			case 'content_filter':
+				throw new InvokeError(
+					InvokeErrorTypes.CONTENT_FILTER,
+					'Content filtered by safety system',
+					undefined,
+					data
+				)
+			default:
+				throw new InvokeError(
+					InvokeErrorTypes.INVALID_SCHEMA,
+					`Unexpected finish_reason: ${choice.finish_reason}`,
+					undefined,
+					data
+				)
+		}
+
+		// Apply normalizeResponse if provided (for fixing format issues automatically)
+		const normalizedData = options?.normalizeResponse ? options.normalizeResponse(data) : data
+		const normalizedChoice = (normalizedData as any).choices?.[0]
+
+		// Get tool name from response
+		const toolCallName = normalizedChoice?.message?.tool_calls?.[0]?.function?.name
+		if (!toolCallName) {
+			throw new InvokeError(
+				InvokeErrorTypes.NO_TOOL_CALL,
+				'No tool call found in response',
+				undefined,
+				data
+			)
+		}
+
+		const tool = tools[toolCallName]
+		if (!tool) {
+			throw new InvokeError(
+				InvokeErrorTypes.UNKNOWN,
+				`Tool "${toolCallName}" not found in tools`,
+				undefined,
+				data
+			)
+		}
+
+		// Extract and parse tool arguments
+		const argString = normalizedChoice.message?.tool_calls?.[0]?.function?.arguments
+		if (!argString) {
+			throw new InvokeError(
+				InvokeErrorTypes.INVALID_TOOL_ARGS,
+				'No tool call arguments found',
+				undefined,
+				data
+			)
+		}
+
+		let parsedArgs: unknown
+		try {
+			parsedArgs = JSON.parse(argString)
+		} catch (error) {
+			throw new InvokeError(
+				InvokeErrorTypes.INVALID_TOOL_ARGS,
+				'Failed to parse tool arguments as JSON',
+				error,
+				data
+			)
+		}
+
+		// Validate with schema
+		const validation = tool.inputSchema.safeParse(parsedArgs)
+		if (!validation.success) {
+			console.error(z.prettifyError(validation.error))
+			throw new InvokeError(
+				InvokeErrorTypes.INVALID_TOOL_ARGS,
+				'Tool arguments validation failed',
+				validation.error,
+				data
+			)
+		}
+		const toolInput = validation.data
+
+		// 5. Execute tool
+		let toolResult: unknown
+		try {
+			toolResult = await tool.execute(toolInput)
+		} catch (error: unknown) {
+			if ((error as any)?.name === 'AbortError') throw error
+			throw new InvokeError(
+				InvokeErrorTypes.TOOL_EXECUTION_ERROR,
+				`Tool execution failed: ${(error as Error)?.message}`,
+				error,
+				data
+			)
+		}
+
+		// Return result
+		return {
+			toolCall: {
+				name: toolCallName,
+				args: toolInput,
+			},
+			toolResult,
+			usage: {
+				promptTokens: data.usage?.prompt_tokens ?? 0,
+				completionTokens: data.usage?.completion_tokens ?? 0,
+				totalTokens: data.usage?.total_tokens ?? 0,
+				cachedTokens: data.usage?.prompt_tokens_details?.cached_tokens,
+				reasoningTokens: data.usage?.completion_tokens_details?.reasoning_tokens,
+			},
+			rawResponse: data,
+			rawRequest: finalRequestBody,
+		}
+	}
+}
diff --git a/packages/llms/src/errors.ts b/packages/llms/src/errors.ts
new file mode 100644
index 0000000..936693e
--- /dev/null
+++ b/packages/llms/src/errors.ts
@@ -0,0 +1,56 @@
+/**
+ * Error types and error handling for LLM invocations.
+ */
+
+export const InvokeErrorTypes = {
+	// Retryable
+	NETWORK_ERROR: 'network_error', // Network error, retry
+	RATE_LIMIT: 'rate_limit', // Rate limit, retry
+	SERVER_ERROR: 'server_error', // 5xx, retry
+	NO_TOOL_CALL: 'no_tool_call', // Model did not call tool
+	INVALID_TOOL_ARGS: 'invalid_tool_args', // Tool args don't match schema
+	TOOL_EXECUTION_ERROR: 'tool_execution_error', // Tool execution error
+	INVALID_RESPONSE: 'invalid_response', // Response body is not valid JSON
+	INVALID_SCHEMA: 'invalid_schema', // Response is valid JSON but doesn't match expected shape
+
+	UNKNOWN: 'unknown',
+
+	// Non-retryable
+	CONFIG_ERROR: 'config_error', // Invalid local configuration or hook
+	AUTH_ERROR: 'auth_error', // Authentication failed
+	CONTEXT_LENGTH: 'context_length', // Prompt too long
+	CONTENT_FILTER: 'content_filter', // Content filtered
+} as const
+
+type InvokeErrorType = (typeof InvokeErrorTypes)[keyof typeof InvokeErrorTypes]
+
+const RETRYABLE_TYPES: readonly InvokeErrorType[] = [
+	InvokeErrorTypes.NETWORK_ERROR,
+	InvokeErrorTypes.RATE_LIMIT,
+	InvokeErrorTypes.SERVER_ERROR,
+	InvokeErrorTypes.NO_TOOL_CALL,
+	InvokeErrorTypes.INVALID_TOOL_ARGS,
+	InvokeErrorTypes.TOOL_EXECUTION_ERROR,
+	InvokeErrorTypes.INVALID_RESPONSE,
+	InvokeErrorTypes.INVALID_SCHEMA,
+	InvokeErrorTypes.UNKNOWN,
+]
+
+export class InvokeError extends Error {
+	type: InvokeErrorType
+	retryable: boolean
+	statusCode?: number
+	/* raw error (provided if this error is caused by another error) */
+	rawError?: unknown
+	/* raw response from the API (provided if this error is caused by an API calling) */
+	rawResponse?: unknown
+
+	constructor(type: InvokeErrorType, message: string, rawError?: unknown, rawResponse?: unknown) {
+		super(message)
+		this.name = 'InvokeError'
+		this.type = type
+		this.retryable = RETRYABLE_TYPES.includes(type)
+		this.rawError = rawError
+		this.rawResponse = rawResponse
+	}
+}
diff --git a/packages/llms/src/index.test.ts b/packages/llms/src/index.test.ts
new file mode 100644
index 0000000..8b816db
--- /dev/null
+++ b/packages/llms/src/index.test.ts
@@ -0,0 +1,114 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+import { InvokeError, InvokeErrorTypes, LLM } from './index'
+import type { LLMClient } from './types'
+
+function makeLLM(maxRetries = 2): LLM {
+	return new LLM({
+		baseURL: 'http://test.local/v1',
+		model: 'gpt-5',
+		maxRetries,
+	})
+}
+
+function abortError(): Error {
+	const err = new Error('aborted')
+	err.name = 'AbortError'
+	return err
+}
+
+describe('LLM.invoke retry behavior', () => {
+	let llm: LLM
+	let client: { invoke: ReturnType<typeof vi.fn> }
+	const signal = new AbortController().signal
+
+	beforeEach(() => {
+		llm = makeLLM(2)
+		client = { invoke: vi.fn() }
+		llm.client = client as unknown as LLMClient
+	})
+
+	it('returns immediately on first success', async () => {
+		client.invoke.mockResolvedValueOnce('ok')
+		const retryListener = vi.fn()
+		llm.addEventListener('retry', retryListener)
+
+		await expect(llm.invoke([], {}, signal)).resolves.toBe('ok')
+		expect(client.invoke).toHaveBeenCalledOnce()
+		expect(retryListener).not.toHaveBeenCalled()
+	})
+
+	it('retries up to maxRetries on retryable errors, then throws last error', async () => {
+		const retryable = new InvokeError(InvokeErrorTypes.NETWORK_ERROR, 'boom')
+		client.invoke
+			.mockRejectedValueOnce(retryable)
+			.mockRejectedValueOnce(retryable)
+			.mockRejectedValueOnce(retryable)
+
+		await expect(llm.invoke([], {}, signal)).rejects.toBe(retryable)
+		// 1 initial + 2 retries = 3 attempts total
+		expect(client.invoke).toHaveBeenCalledTimes(3)
+	})
+
+	it('succeeds on retry after transient failure', async () => {
+		const retryable = new InvokeError(InvokeErrorTypes.RATE_LIMIT, 'slow down')
+		client.invoke.mockRejectedValueOnce(retryable).mockResolvedValueOnce('ok')
+
+		await expect(llm.invoke([], {}, signal)).resolves.toBe('ok')
+		expect(client.invoke).toHaveBeenCalledTimes(2)
+	})
+
+	it('emits "retry" events with attempt count and lastError', async () => {
+		const err1 = new InvokeError(InvokeErrorTypes.NETWORK_ERROR, 'first')
+		const err2 = new InvokeError(InvokeErrorTypes.NETWORK_ERROR, 'second')
+		client.invoke
+			.mockRejectedValueOnce(err1)
+			.mockRejectedValueOnce(err2)
+			.mockResolvedValueOnce('ok')
+
+		const events: { attempt: number; maxAttempts: number; lastError: Error }[] = []
+		llm.addEventListener('retry', (e) => {
+			events.push((e as CustomEvent).detail)
+		})
+
+		await llm.invoke([], {}, signal)
+
+		expect(events).toEqual([
+			{ attempt: 1, maxAttempts: 2, lastError: err1 },
+			{ attempt: 2, maxAttempts: 2, lastError: err2 },
+		])
+	})
+
+	it('does not retry on AbortError, throws immediately', async () => {
+		const err = abortError()
+		client.invoke.mockRejectedValueOnce(err)
+
+		await expect(llm.invoke([], {}, signal)).rejects.toBe(err)
+		expect(client.invoke).toHaveBeenCalledOnce()
+	})
+
+	it('does not retry on non-retryable InvokeError (AUTH_ERROR)', async () => {
+		const err = new InvokeError(InvokeErrorTypes.AUTH_ERROR, 'bad token')
+		client.invoke.mockRejectedValueOnce(err)
+
+		await expect(llm.invoke([], {}, signal)).rejects.toBe(err)
+		expect(client.invoke).toHaveBeenCalledOnce()
+	})
+
+	it('does not retry on non-retryable InvokeError (CONFIG_ERROR)', async () => {
+		const err = new InvokeError(InvokeErrorTypes.CONFIG_ERROR, 'bad config')
+		client.invoke.mockRejectedValueOnce(err)
+
+		await expect(llm.invoke([], {}, signal)).rejects.toBe(err)
+		expect(client.invoke).toHaveBeenCalledOnce()
+	})
+
+	it('retries plain (non-InvokeError) errors as unknown failures', async () => {
+		// Plain errors are treated as retryable by withRetry (only InvokeError carries retryable flag)
+		const plain = new TypeError('weird')
+		client.invoke.mockRejectedValueOnce(plain).mockResolvedValueOnce('ok')
+
+		await expect(llm.invoke([], {}, signal)).resolves.toBe('ok')
+		expect(client.invoke).toHaveBeenCalledTimes(2)
+	})
+})
diff --git a/packages/llms/src/index.ts b/packages/llms/src/index.ts
new file mode 100644
index 0000000..5c2e0ec
--- /dev/null
+++ b/packages/llms/src/index.ts
@@ -0,0 +1,109 @@
+import { OpenAIClient } from './OpenAIClient'
+import { InvokeError, InvokeErrorTypes } from './errors'
+import type {
+	InvokeOptions,
+	InvokeResult,
+	LLMClient,
+	LLMConfig,
+	Message,
+	ResolvedLLMConfig,
+	Tool,
+} from './types'
+
+export { InvokeError, InvokeErrorTypes }
+export type { InvokeOptions, InvokeResult, LLMClient, LLMConfig, Message, Tool }
+
+/**
+ * LLM module
+ */
+export class LLM extends EventTarget {
+	config: ResolvedLLMConfig
+	client: LLMClient
+
+	constructor(config: LLMConfig) {
+		super()
+		this.config = parseLLMConfig(config)
+
+		// Default to OpenAI client
+		this.client = new OpenAIClient(this.config)
+	}
+
+	/**
+	 * - call llm api *once*
+	 * - invoke tool call *once*
+	 * - return the result of the tool
+	 */
+	async invoke(
+		messages: Message[],
+		tools: Record<string, Tool>,
+		abortSignal: AbortSignal,
+		options?: InvokeOptions
+	): Promise<InvokeResult> {
+		return await withRetry(async () => this.client.invoke(messages, tools, abortSignal, options), {
+			maxRetries: this.config.maxRetries,
+			onRetry: (attempt, lastError) => {
+				this.dispatchEvent(
+					new CustomEvent('retry', {
+						detail: { attempt, maxAttempts: this.config.maxRetries, lastError },
+					})
+				)
+			},
+		})
+	}
+}
+
+/**
+ * Retry a function until it succeeds or reaches the maximum number of retries.
+ */
+async function withRetry<T>(
+	fn: () => Promise<T>,
+	settings: {
+		maxRetries: number
+		onRetry: (attempt: number, lastError: Error) => void
+	}
+): Promise<T> {
+	let attempt = 0
+	while (true) {
+		try {
+			return await fn()
+		} catch (error: unknown) {
+			if ((error as any)?.name === 'AbortError') throw error
+			if (error instanceof InvokeError && !error.retryable) throw error
+			attempt++
+			if (attempt > settings.maxRetries) throw error
+
+			console.debug('[LLM] retryable failure, will retry:', error)
+			settings.onRetry(attempt, error as Error)
+
+			await new Promise((resolve) => setTimeout(resolve, 100))
+		}
+	}
+}
+
+export function parseLLMConfig(config: LLMConfig): ResolvedLLMConfig {
+	// Runtime validation as defensive programming (types already guarantee these)
+	if (!config.baseURL || !config.model) {
+		throw new Error(
+			'[PageAgent] LLM configuration required. Please provide: baseURL, model. ' +
+				'See: https://alibaba.github.io/page-agent/docs/features/models'
+		)
+	}
+
+	if (config.temperature !== undefined) {
+		console.warn(
+			'[PageAgent] LLMConfig.temperature is deprecated and will be removed in a future version. ' +
+				'Use transformRequestBody to set it only for models you have verified accept it.'
+		)
+	}
+
+	return {
+		baseURL: config.baseURL,
+		model: config.model,
+		apiKey: config.apiKey || '',
+		temperature: config.temperature,
+		maxRetries: config.maxRetries ?? 2,
+		transformRequestBody: config.transformRequestBody ?? ((requestBody) => requestBody),
+		disableNamedToolChoice: config.disableNamedToolChoice ?? false,
+		customFetch: (config.customFetch ?? fetch).bind(globalThis), // fetch will be illegal unless bound
+	}
+}
diff --git a/packages/llms/src/models.live.test.ts b/packages/llms/src/models.live.test.ts
new file mode 100644
index 0000000..467ceae
--- /dev/null
+++ b/packages/llms/src/models.live.test.ts
@@ -0,0 +1,230 @@
+/**
+ * Live compatibility test — hits real provider APIs.
+ *
+ * Purpose: verify request formatting and `modelPatch` (see `utils.ts`) work
+ * for every model below, across the providers that serve them. Not a
+ * correctness/quality eval — the tool call is trivial and forced via
+ * `toolChoiceName`, so a failure here means the request/response shape is
+ * wrong for that model, not that the model is "dumb".
+ *
+ * Tests `OpenAIClient` directly (not the `LLM` retry wrapper), so a failure
+ * always reflects the very first request/response — no retry can mask it.
+ *
+ * Per the `*.live.test.ts` convention this suite is excluded from `npm test`
+ * (slow, costs tokens) — run it manually with `npm run test:live`. Each
+ * provider's tests skip (not fail) when its `TESTING_*_KEY` env var is
+ * absent. Keys live in the repo-root `.env`:
+ *
+ *   TESTING_OPENROUTER_KEY=...
+ *   TESTING_DEEPSEEK_KEY=...
+ *   TESTING_ALIYUN_KEY=...
+ */
+import { config as dotenvConfig } from 'dotenv'
+import { dirname, resolve } from 'path'
+import { fileURLToPath } from 'url'
+import { describe, expect, it } from 'vitest'
+import * as z from 'zod/v4'
+
+import { OpenAIClient } from './OpenAIClient'
+import { parseLLMConfig } from './index'
+import type { Message, Tool } from './types'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+dotenvConfig({ path: resolve(__dirname, '../../../.env'), quiet: true })
+
+const TEST_TIMEOUT = 30_000
+
+/**
+ * Mirrors `packages/website/src/pages/docs/features/models/page.tsx`.
+ * This package cannot depend on the website, so the list is duplicated here.
+ * Keep both lists in sync manually when models are added or renamed.
+ */
+const MODEL_GROUPS: Record<string, string[]> = {
+	Qwen: [
+		'qwen3.7-max',
+		'qwen3.7-plus',
+		'qwen3.6-max',
+		'qwen3.6-plus',
+		'qwen3.6-flash',
+		'qwen3.5-plus',
+		'qwen3.5-flash',
+		'qwen3-max',
+	],
+	OpenAI: [
+		'gpt-5.6-sol',
+		'gpt-5.6-terra',
+		'gpt-5.6-luna',
+		'gpt-5.5',
+		'gpt-5.4',
+		'gpt-5.4-mini',
+		'gpt-5.4-nano',
+		'gpt-5.2',
+		'gpt-5.1',
+		'gpt-5',
+		'gpt-5-mini',
+		'gpt-4.1',
+		'gpt-4.1-mini',
+	],
+	DeepSeek: ['deepseek-v4-pro', 'deepseek-v4-flash', 'deepseek-3.2'],
+	Google: [
+		'gemini-3.5-flash',
+		'gemini-3.1-pro',
+		'gemini-3.1-flash-lite',
+		'gemini-2.5-pro',
+		'gemini-2.5-flash',
+	],
+	Anthropic: [
+		'claude-sonnet-5',
+		'claude-opus-4-8',
+		'claude-opus-4-7',
+		'claude-opus-4-6',
+		'claude-opus-4-5',
+		'claude-sonnet-4-5',
+		'claude-haiku-4-5',
+	],
+	MiniMax: ['MiniMax-M3', 'MiniMax-M2.7', 'MiniMax-M2.5'],
+	xAI: ['grok-4.5', 'grok-4.3', 'grok-build-0.1'],
+	Tencent: ['hy3'],
+	MoonshotAI: ['kimi-k2.7-code', 'kimi-k2.6', 'kimi-k2.5'],
+	'Z.AI': ['glm-5.2', 'glm-5.1', 'glm-5', 'glm-4.7'],
+}
+
+/**
+ * OpenRouter lists every model as `<vendor-slug>/<model-id>`, lowercase.
+ * See the commented-out entries in the repo-root `.env` for real examples,
+ * e.g. `x-ai/grok-4.1-fast`, `qwen/qwen3-coder-next`, `deepseek/deepseek-v3.2-exp`.
+ */
+const OPENROUTER_VENDOR_SLUG: Record<string, string> = {
+	Qwen: 'qwen',
+	OpenAI: 'openai',
+	DeepSeek: 'deepseek',
+	Google: 'google',
+	Anthropic: 'anthropic',
+	MiniMax: 'minimax',
+	xAI: 'x-ai',
+	Tencent: 'tencent',
+	MoonshotAI: 'moonshotai',
+	'Z.AI': 'z-ai',
+}
+
+/**
+ * Overrides for models whose OpenRouter id doesn't match the
+ * `<vendor-slug>/<lowercased-name>` heuristic — dated snapshots, "-preview"
+ * suffixes, "v"-prefixed versions, or dots instead of hyphens in the
+ * version number. Verified against `GET https://openrouter.ai/api/v1/models`
+ * on 2026-07-10; re-check when models are added to `MODEL_GROUPS`.
+ */
+const OPENROUTER_ID_OVERRIDES: Record<string, string> = {
+	'qwen3.6-max': 'qwen/qwen3.6-max-preview',
+	'qwen3.5-plus': 'qwen/qwen3.5-plus-20260420',
+	'qwen3.5-flash': 'qwen/qwen3.5-flash-02-23',
+	'deepseek-3.2': 'deepseek/deepseek-v3.2',
+	'gemini-3.1-pro': 'google/gemini-3.1-pro-preview',
+	'claude-opus-4-8': 'anthropic/claude-opus-4.8',
+	'claude-opus-4-7': 'anthropic/claude-opus-4.7',
+	'claude-opus-4-6': 'anthropic/claude-opus-4.6',
+	'claude-opus-4-5': 'anthropic/claude-opus-4.5',
+	'claude-sonnet-4-5': 'anthropic/claude-sonnet-4.5',
+	'claude-haiku-4-5': 'anthropic/claude-haiku-4.5',
+}
+
+/**
+ * Derive a model's OpenRouter id from its brand (a `MODEL_GROUPS` key) and
+ * native model name.
+ */
+function toOpenRouterModelId(brand: string, model: string): string {
+	if (model in OPENROUTER_ID_OVERRIDES) return OPENROUTER_ID_OVERRIDES[model]
+	const slug = OPENROUTER_VENDOR_SLUG[brand]
+	if (!slug) throw new Error(`No OpenRouter vendor slug mapped for brand "${brand}"`)
+	return `${slug}/${model.toLowerCase()}`
+}
+
+const PROVIDERS = {
+	openrouter: {
+		baseURL: 'https://openrouter.ai/api/v1',
+		apiKey: process.env.TESTING_OPENROUTER_KEY,
+	},
+	aliyun: {
+		baseURL: 'https://dashscope.aliyuncs.com/compatible-mode/v1',
+		apiKey: process.env.TESTING_ALIYUN_KEY,
+	},
+	deepseek: {
+		baseURL: 'https://api.deepseek.com',
+		apiKey: process.env.TESTING_DEEPSEEK_KEY,
+	},
+} as const
+
+const ECHO_TOOL: Tool<{ message: string }, string> = {
+	description: 'Echo back the given message in uppercase.',
+	inputSchema: z.object({ message: z.string() }),
+	execute: async ({ message }) => message.toUpperCase(),
+}
+
+const PROMPT: Message[] = [
+	{
+		role: 'user',
+		content: 'Call the "echo" tool with message set to "ping". You must call the tool.',
+	},
+]
+
+async function expectEchoToolCall(baseURL: string, apiKey: string, model: string) {
+	const client = new OpenAIClient(parseLLMConfig({ baseURL, apiKey, model }))
+	const result = await client.invoke(PROMPT, { echo: ECHO_TOOL }, new AbortController().signal, {
+		toolChoiceName: 'echo',
+	})
+	expect(result.toolResult).toBe('PING')
+}
+
+describe.concurrent('OpenRouter — all listed models', () => {
+	const { baseURL, apiKey } = PROVIDERS.openrouter
+
+	for (const [brand, models] of Object.entries(MODEL_GROUPS)) {
+		for (const model of models) {
+			const id = toOpenRouterModelId(brand, model)
+			it.skipIf(!apiKey)(
+				id,
+				async () => {
+					await expectEchoToolCall(baseURL, apiKey!, id)
+				},
+				TEST_TIMEOUT
+			)
+		}
+	}
+})
+
+// Aliyun native ids that don't match the display name in MODEL_GROUPS.
+const ALIYUN_ID_OVERRIDES: Record<string, string> = {
+	'qwen3.6-max': 'qwen3.6-max-preview',
+}
+
+describe.concurrent('Aliyun DashScope — Qwen native', () => {
+	const { baseURL, apiKey } = PROVIDERS.aliyun
+
+	for (const model of MODEL_GROUPS.Qwen) {
+		const id = ALIYUN_ID_OVERRIDES[model] ?? model
+		it.skipIf(!apiKey)(
+			id,
+			async () => {
+				await expectEchoToolCall(baseURL, apiKey!, id)
+			},
+			TEST_TIMEOUT
+		)
+	}
+})
+
+describe.concurrent('DeepSeek — native', () => {
+	const { baseURL, apiKey } = PROVIDERS.deepseek
+	// deepseek-3.2 isn't served on DeepSeek's own API (only via OpenRouter
+	// resellers) — its official API only accepts deepseek-v4-pro/-flash.
+	const nativeModels = MODEL_GROUPS.DeepSeek.filter((model) => model !== 'deepseek-3.2')
+
+	for (const model of nativeModels) {
+		it.skipIf(!apiKey)(
+			model,
+			async () => {
+				await expectEchoToolCall(baseURL, apiKey!, model)
+			},
+			TEST_TIMEOUT
+		)
+	}
+})
diff --git a/packages/llms/src/types.ts b/packages/llms/src/types.ts
new file mode 100644
index 0000000..340496f
--- /dev/null
+++ b/packages/llms/src/types.ts
@@ -0,0 +1,127 @@
+/**
+ * Core types for LLM integration
+ */
+import type * as z from 'zod/v4'
+
+/**
+ * Message format - OpenAI standard (industry standard)
+ */
+export interface Message {
+	role: 'system' | 'user' | 'assistant' | 'tool'
+	content?: string | null
+	tool_calls?: {
+		id: string
+		type: 'function'
+		function: {
+			name: string
+			arguments: string // JSON string
+		}
+	}[]
+	tool_call_id?: string
+	name?: string
+}
+
+/**
+ * Tool definition - uses Zod schema (LLM-agnostic)
+ * Supports generics for type-safe parameters and return values
+ */
+export interface Tool<TParams = any, TResult = any> {
+	// name: string
+	description?: string
+	inputSchema: z.ZodType<TParams>
+	execute: (args: TParams) => Promise<TResult>
+}
+
+/**
+ * Invoke options for LLM call
+ */
+export interface InvokeOptions {
+	/**
+	 * Force LLM to call a specific tool by name.
+	 * If provided: tool_choice = { type: 'function', function: { name: toolChoiceName } }
+	 * If not provided: tool_choice = 'required' (must call some tool, but model chooses which)
+	 */
+	toolChoiceName?: string
+	/**
+	 * Response normalization function.
+	 * Called before parsing the response.
+	 * Used to fix various response format errors from the model.
+	 */
+	normalizeResponse?: (response: any) => any
+}
+
+/**
+ * LLM Client interface
+ * Note: Does not use generics because each tool in the tools array has different types
+ */
+export interface LLMClient {
+	invoke(
+		messages: Message[],
+		tools: Record<string, Tool>,
+		abortSignal?: AbortSignal,
+		options?: InvokeOptions
+	): Promise<InvokeResult>
+}
+
+/**
+ * Invoke result (strict typing, supports generics)
+ */
+export interface InvokeResult<TResult = unknown> {
+	toolCall: {
+		// id?: string // OpenAI's tool_call_id
+		name: string
+		args: any
+	}
+	toolResult: TResult // Supports generics, but defaults to unknown
+	usage: {
+		promptTokens: number
+		completionTokens: number
+		totalTokens: number
+		cachedTokens?: number // Prompt cache hits
+		reasoningTokens?: number // OpenAI o1 series reasoning tokens
+	}
+	rawResponse?: unknown // Raw response for debugging
+	rawRequest?: unknown // Raw request for debugging
+}
+
+/**
+ * LLM configuration
+ */
+export interface LLMConfig {
+	baseURL: string
+	model: string
+	apiKey?: string
+
+	/**
+	 * @deprecated No longer a standard parameter; many models reject it outright.
+	 * Use `transformRequestBody` to set it only for models you've verified.
+	 */
+	temperature?: number
+
+	maxRetries?: number
+
+	/**
+	 * Transform the final request body before sending it to the provider.
+	 * Use this to implement provider-specific request tweaks such as caching hints or custom flags.
+	 *
+	 * Return a new object, or mutate the input object and return undefined.
+	 */
+	transformRequestBody?: (
+		requestBody: Record<string, unknown>
+	) => Record<string, unknown> | undefined
+
+	/**
+	 * remove the tool_choice field from the request.
+	 * @note fix "Invalid tool_choice type: 'object'" for some LLMs.
+	 */
+	disableNamedToolChoice?: boolean
+
+	/**
+	 * Custom fetch function for LLM API requests.
+	 * Use this to customize headers, credentials, proxy, etc.
+	 * The response should follow OpenAI API format.
+	 */
+	customFetch?: typeof globalThis.fetch
+}
+
+export type ResolvedLLMConfig = Required<Omit<LLMConfig, 'temperature'>> & { temperature?: number }
diff --git a/packages/llms/src/utils.test.ts b/packages/llms/src/utils.test.ts
new file mode 100644
index 0000000..7e02697
--- /dev/null
+++ b/packages/llms/src/utils.test.ts
@@ -0,0 +1,15 @@
+import { describe, expect, it } from 'vitest'
+
+import { modelPatch, normalizeModelName } from './utils'
+
+describe('normalizeModelName', () => {
+	it.each([
+		['gpt-5.2', 'gpt-52'],
+		['gpt_5_2', 'gpt52'],
+		['GPT-52-2026-01-01', 'gpt-52-2026-01-01'],
+		['openai/gpt-5.2-chat', 'gpt-52-chat'],
+		['claude_sonnet4_5', 'claudesonnet45'],
+	])('%s -> %s', (input, expected) => {
+		expect(normalizeModelName(input)).toBe(expected)
+	})
+})
diff --git a/packages/llms/src/utils.ts b/packages/llms/src/utils.ts
new file mode 100644
index 0000000..cfebb81
--- /dev/null
+++ b/packages/llms/src/utils.ts
@@ -0,0 +1,235 @@
+/**
+ * Utility functions for LLM integration
+ */
+import chalk from 'chalk'
+import * as z from 'zod/v4'
+
+import type { Tool } from './types'
+
+const debug = console.debug.bind(console, chalk.gray('[LLM]'))
+
+/**
+ * Convert Zod schema to OpenAI tool format
+ * Uses Zod 4 native z.toJSONSchema()
+ */
+export function zodToOpenAITool(name: string, tool: Tool) {
+	return {
+		type: 'function' as const,
+		function: {
+			name,
+			description: tool.description,
+			parameters: z.toJSONSchema(tool.inputSchema, { target: 'openapi-3.0' }),
+		},
+	}
+}
+
+/**
+ * Patch model specific parameters. Only patches known models.
+ *
+ * @purpose
+ * - Reconcile the differences in the parameter schema each model accepts.
+ * - Disable thinking/reasoning, or lower it to the minimum where a full disable is impossible.
+ * - Minimize returned tokens.
+ * - Raise temperature for known smaller models to improve auto-recovery odds.
+ * @note Honor temperature if explicitly set by the user
+ *
+ * @todo Need vendor-specific patches.
+ * Local and 3rd-party hosted models may have different schema.
+ */
+export function modelPatch(body: Record<string, any>, baseURL?: string) {
+	const model: string = body.model || ''
+	if (!model) return body
+
+	const provider = getProvider(baseURL)
+
+	const modelName = normalizeModelName(model)
+
+	if (modelName.startsWith('qwen')) {
+		debug('Patch Qwen: disable thinking')
+		body.enable_thinking = false
+		if (body.temperature === undefined && !/max|plus/.test(modelName)) {
+			debug('Patch Qwen: raise temperature to 1.0')
+			body.temperature = 1.0
+		}
+	}
+
+	if (modelName.startsWith('deepseek')) {
+		debug('Patch DeepSeek: disable thinking, remove tool_choice')
+		body.thinking = { type: 'disabled' }
+		delete body.tool_choice
+	}
+
+	if (modelName.startsWith('gpt')) {
+		if (modelName.startsWith('gpt-5')) {
+			body.verbosity = 'low'
+		}
+
+		// Since gpt-5.4, /chat/completions rejects any explicit reasoning_effort
+		// when function tools are present. Newer models are expected to follow.
+		// - gpt-5.1 / gpt-5.2 can fully disable reasoning
+		// - gpt-5 / -mini / -nano bottom out at "minimal"
+		// - everything else (gpt-4.x, chat-latest, gpt-5.4+) must not receive it
+		if (modelName.includes('chat-latest')) {
+			debug('Patch chat-latest: omit reasoning_effort and temperature')
+			delete body.reasoning_effort
+			delete body.temperature
+		} else if (/^gpt-5[12](-|$)/.test(modelName)) {
+			debug('Patch GPT-5.1/5.2: reasoning_effort=none')
+			body.reasoning_effort = 'none'
+		} else if (/^gpt-5(-|$)/.test(modelName)) {
+			debug('Patch GPT-5: reasoning_effort=minimal')
+			body.reasoning_effort = 'minimal'
+		} else {
+			debug('Patch GPT: omit reasoning_effort')
+			delete body.reasoning_effort
+		}
+	}
+
+	if (modelName.startsWith('claude')) {
+		if (/opus|sonnet|haiku/.test(modelName)) {
+			debug('Patch Claude: disable thinking')
+			body.thinking = { type: 'disabled' }
+
+			if (provider !== 'openrouter') {
+				// Convert tool_choice to Claude format
+				if (body.tool_choice === 'required') {
+					// 'required' -> { type: 'any' } (must call some tool)
+					debug('Applying Claude patch: convert tool_choice "required" to { type: "any" }')
+					body.tool_choice = { type: 'any' }
+				} else if (body.tool_choice?.function?.name) {
+					// { type: 'function', function: { name: '...' } } -> { type: 'tool', name: '...' }
+					debug('Applying Claude patch: convert tool_choice format')
+					body.tool_choice = { type: 'tool', name: body.tool_choice.function.name }
+				}
+			}
+		} else {
+			debug('Patch Claude: reasoning_effort=low')
+			body.reasoning_effort = 'low'
+
+			// Fable and mythos can not disable adaptive thinking.
+			// Claude does not support tool_choice with extended thinking.
+			// These 2 concepts are blurred. Basically no tool_choice with thinking.
+			delete body.tool_choice
+		}
+	}
+
+	if (modelName.startsWith('gemini')) {
+		debug('Patch Gemini: reasoning_effort=low')
+		body.reasoning_effort = 'low'
+		if (/^gemini-25(?!.*pro)/.test(modelName)) {
+			debug('Patch Gemini 2.5 non-Pro: reasoning_effort=none')
+			body.reasoning_effort = 'none'
+		} else if (
+			modelName.startsWith('gemini-35-flash') ||
+			modelName.startsWith('gemini-31-flash-lite') ||
+			modelName.startsWith('gemini-3-flash')
+		) {
+			debug('Patch Gemini 3.x Flash/Lite: reasoning_effort=minimal')
+			body.reasoning_effort = 'minimal'
+		}
+	}
+
+	if (modelName.startsWith('glm')) {
+		debug('Patch GLM: disable thinking')
+		body.thinking = { type: 'disabled' }
+	}
+
+	if (modelName.startsWith('hy')) {
+		debug('Patch Hunyuan: disable thinking, reasoning_effort=low')
+		body.thinking = { type: 'disabled' }
+		body.reasoning_effort = 'low'
+	}
+
+	if (modelName.startsWith('grok')) {
+		if (/^grok-4-?3/.test(modelName)) {
+			debug('Patch Grok 4.3: reasoning_effort=none')
+			body.reasoning_effort = 'none'
+		} else if (modelName.startsWith('grok-3-mini') || modelName.startsWith('grok-code-fast')) {
+			debug('Patch Grok mini/code: reasoning_effort=low')
+			body.reasoning_effort = 'low'
+		}
+	}
+
+	if (modelName.startsWith('kimi')) {
+		if (!modelName.includes('code')) {
+			// kimi-k2.7-code cannot disable thinking
+			debug('Patch Kimi: disable thinking')
+			body.thinking = { type: 'disabled' }
+		}
+	}
+
+	if (modelName.startsWith('minimax')) {
+		debug('Patch MiniMax: remove parallel_tool_calls')
+		delete body.parallel_tool_calls
+
+		if (modelName.includes('m3')) {
+			// Only M3 can disable thinking
+			debug('Patch MiniMax: disable thinking')
+			body.thinking = { type: 'disabled' }
+		}
+	}
+
+	// provider patches
+
+	if (provider === 'openrouter') {
+		// openrouter use reasoning object instead of reasoning_effort
+
+		const reasoningEffort = body.reasoning_effort
+		const reasoningDisabled =
+			body.thinking?.type === 'disabled' ||
+			body.enable_thinking === false ||
+			reasoningEffort === 'none'
+
+		if (reasoningDisabled) {
+			body.reasoning = { enabled: false }
+		} else if (reasoningEffort) {
+			body.reasoning = { enabled: true, effort: reasoningEffort }
+		}
+	}
+
+	return body
+}
+
+/**
+ * check if a given model ID fits a specific model name
+ *
+ * @note
+ * Different model providers may use different model IDs for the same model.
+ * For example, openai's `gpt-5.2` may called:
+ *
+ * - `gpt-5.2-version`
+ * - `gpt-5_2-date`
+ * - `GPT-52-version-date`
+ * - `openai/gpt-5.2-chat`
+ *
+ * They should be treated as the same model.
+ * Normalize them to `gpt-52`
+ */
+export function normalizeModelName(modelName: string): string {
+	let normalizedName = modelName.toLowerCase()
+
+	// remove prefix before '/'
+	if (normalizedName.includes('/')) {
+		normalizedName = normalizedName.split('/')[1]
+	}
+
+	// remove '_'
+	normalizedName = normalizedName.replace(/_/g, '')
+
+	// remove '.'
+	normalizedName = normalizedName.replace(/\./g, '')
+
+	return normalizedName
+}
+
+export function getProvider(baseURL?: string): 'openrouter' | undefined {
+	if (!baseURL) return undefined
+	try {
+		const url = new URL(baseURL)
+		const hostname = url.hostname
+		if (hostname === 'openrouter.ai') return 'openrouter'
+		return undefined
+	} catch (e) {
+		return undefined
+	}
+}
diff --git a/packages/llms/tsconfig.json b/packages/llms/tsconfig.json
new file mode 100644
index 0000000..d45abe9
--- /dev/null
+++ b/packages/llms/tsconfig.json
@@ -0,0 +1,8 @@
+{
+    "extends": "../../tsconfig.base.json",
+    "compilerOptions": {
+        "tsBuildInfoFile": "./node_modules/.tmp/tsconfig.tsbuildinfo"
+    },
+    "include": ["src/**/*.ts"],
+    "exclude": ["dist", "node_modules"]
+}
diff --git a/packages/llms/vite.config.js b/packages/llms/vite.config.js
new file mode 100644
index 0000000..c126e3c
--- /dev/null
+++ b/packages/llms/vite.config.js
@@ -0,0 +1,45 @@
+// @ts-check
+import chalk from 'chalk'
+import { dirname, resolve } from 'path'
+import dts from 'unplugin-dts/vite'
+import { fileURLToPath } from 'url'
+import { defineConfig } from 'vite'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+
+console.log(chalk.cyan(`📦 Building @page-agent/llms`))
+
+export default defineConfig({
+	clearScreen: false,
+	plugins: [
+		dts({
+			include: ['src/**/*.ts'],
+			exclude: ['src/**/*.test.ts'],
+			bundleTypes: true,
+			compilerOptions: {
+				composite: true,
+				noEmit: false,
+				emitDeclarationOnly: true,
+				declaration: true,
+			},
+		}),
+	],
+	publicDir: false,
+	build: {
+		lib: {
+			entry: resolve(__dirname, 'src/index.ts'),
+			name: 'PageAgentLLMs',
+			fileName: 'page-agent-llms',
+			formats: ['es'],
+		},
+		outDir: resolve(__dirname, 'dist', 'lib'),
+		rollupOptions: {
+			external: ['chalk', 'zod', 'zod/v4'],
+		},
+		minify: false,
+		sourcemap: true,
+	},
+	define: {
+		'process.env.NODE_ENV': '"production"',
+	},
+})
diff --git a/packages/llms/vitest.config.js b/packages/llms/vitest.config.js
new file mode 100644
index 0000000..82891de
--- /dev/null
+++ b/packages/llms/vitest.config.js
@@ -0,0 +1,27 @@
+import { configDefaults, defineConfig } from 'vitest/config'
+
+// Convention: `*.live.test.ts` hits real provider APIs (slow, costs tokens)
+// and only runs via `npm run test:live`. Everything else runs on `npm test`.
+export default defineConfig({
+	test: {
+		// Suppress console output from passing tests; failed tests still get their logs.
+		silent: 'passed-only',
+		projects: [
+			{
+				test: {
+					name: 'llms',
+					include: ['src/**/*.test.ts'],
+					exclude: [...configDefaults.exclude, 'src/**/*.live.test.ts'],
+				},
+			},
+			{
+				test: {
+					name: 'llms:live',
+					include: ['src/**/*.live.test.ts'],
+					// Keep live provider suites under OpenRouter's ~20 req/min free-route cap.
+					maxConcurrency: 2,
+				},
+			},
+		],
+	},
+})
diff --git a/packages/mcp/README.md b/packages/mcp/README.md
new file mode 100644
index 0000000..94ff096
--- /dev/null
+++ b/packages/mcp/README.md
@@ -0,0 +1,93 @@
+# @page-agent/mcp
+
+MCP server that lets AI agent clients (Claude Desktop, Copilot, etc.) control your browser through the [Page Agent](https://github.com/alibaba/page-agent) extension.
+
+## Prerequisites
+
+- Node.js >= 20
+- [Page Agent Extension](https://chromewebstore.google.com/detail/page-agent-ext/akldabonmimlicnjlflnapfeklbfemhj) installed in Chrome
+- An LLM API key (OpenAI-compatible)
+
+## Installation
+
+### Claude Desktop
+
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+    "mcpServers": {
+        "page-agent": {
+            "command": "npx",
+            "args": ["-y", "@page-agent/mcp"],
+            "env": {
+                "LLM_BASE_URL": "https://dashscope.aliyuncs.com/compatible-mode/v1",
+                "LLM_API_KEY": "sk-xxx",
+                "LLM_MODEL_NAME": "qwen3.5-plus"
+            }
+        }
+    }
+}
+```
+
+### Cursor / Copilot
+
+Same format — add the config to the MCP settings of your client.
+
+## MCP Tools
+
+| Tool           | Input              | Description                                           |
+| -------------- | ------------------ | ----------------------------------------------------- |
+| `execute_task` | `{ task: string }` | Execute a browser task in natural language. Blocking. |
+| `get_status`   | —                  | Returns `{ connected, busy }`                         |
+| `stop_task`    | —                  | Stop the currently running task.                      |
+
+## Environment Variables
+
+| Variable         | Default | Description           |
+| ---------------- | ------- | --------------------- |
+| `LLM_BASE_URL`   | —       | LLM API base URL      |
+| `LLM_API_KEY`    | —       | LLM API key           |
+| `LLM_MODEL_NAME` | —       | Model name            |
+| `PORT`           | `38401` | HTTP + WebSocket port |
+
+## How It Works
+
+```
+┌──────────────┐  stdio   ┌──────────────────┐  WebSocket   ┌──────────────┐
+│ Claude /     │◄────────►│ @page-agent/mcp  │◄────────────►│ Hub tab      │
+│ Copilot      │  (MCP)   │ (Node.js)        │  (localhost) │ (extension)  │
+└──────────────┘          └──────────────────┘              └──────┬───────┘
+                                   │                               │
+                                   │ HTTP                          │ useAgent
+                                   ▼                               ▼
+                          ┌──────────────────┐              ┌──────────────┐
+                          │ Launcher page    │              │ MultiPage    │
+                          │ (localhost:PORT) │              │ Agent        │
+                          └──────────────────┘              └──────────────┘
+```
+
+1. Agent client starts the MCP server via stdio (`npx @page-agent/mcp`).
+2. Server starts HTTP + WS on `localhost:PORT`, opens the launcher page in browser.
+3. Launcher page triggers the extension to open a **hub tab** (`hub.html?ws=PORT`).
+4. Hub connects to the WS server. MCP tools now proxy tasks to the hub.
+
+The hub tab speaks a generic WebSocket protocol (defined in `hub-ws.ts` in the extension package) and has no knowledge of MCP. See the hub's protocol docs for message format details.
+
+## Architecture
+
+Pure JS ESM, no build step. Source files are the published artifacts.
+
+```
+src/
+├── index.js        # CLI entry: MCP server (stdio) + opens launcher
+├── hub-bridge.js   # HTTP server + WebSocket bridge to hub tab
+└── launcher.html   # Bootstrap page: detects extension, triggers hub open
+```
+
+## Dev
+
+```bash
+npm run dev:ext
+npx @modelcontextprotocol/inspector node packages/mcp/src/index.js
+```
diff --git a/packages/mcp/package.json b/packages/mcp/package.json
new file mode 100644
index 0000000..7c5b363
--- /dev/null
+++ b/packages/mcp/package.json
@@ -0,0 +1,35 @@
+{
+    "name": "@page-agent/mcp",
+    "private": false,
+    "version": "1.12.1",
+    "type": "module",
+    "bin": {
+        "page-agent-mcp": "src/index.js"
+    },
+    "files": [
+        "src/"
+    ],
+    "description": "MCP server for controlling the browser via Page Agent extension",
+    "keywords": [
+        "page-agent",
+        "mcp",
+        "browser-automation",
+        "chrome-extension"
+    ],
+    "author": "Simon<gaomeng1900>",
+    "license": "MIT",
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/alibaba/page-agent.git",
+        "directory": "packages/mcp"
+    },
+    "homepage": "https://alibaba.github.io/page-agent/",
+    "engines": {
+        "node": ">=20"
+    },
+    "dependencies": {
+        "@modelcontextprotocol/sdk": "^1.29.0",
+        "ws": "^8.21.0",
+        "zod": "^4.4.3"
+    }
+}
diff --git a/packages/mcp/src/hub-bridge.js b/packages/mcp/src/hub-bridge.js
new file mode 100644
index 0000000..e7a22e1
--- /dev/null
+++ b/packages/mcp/src/hub-bridge.js
@@ -0,0 +1,139 @@
+#!/usr/bin/env node
+import { readFileSync } from 'node:fs'
+import http from 'node:http'
+import { fileURLToPath } from 'node:url'
+import { WebSocketServer } from 'ws'
+
+const EXT_ID = 'akldabonmimlicnjlflnapfeklbfemhj'
+const STORE_URL = `https://chromewebstore.google.com/detail/page-agent-ext/${EXT_ID}`
+const LOOPBACK_HOST = 'localhost'
+
+const launcherTemplate = readFileSync(
+	fileURLToPath(new URL('./launcher.html', import.meta.url)),
+	'utf-8'
+)
+
+/**
+ * HTTP + WebSocket bridge to the hub.html extension tab.
+ * - HTTP serves the launcher page (triggers extension to open hub)
+ * - WS carries execute/stop commands and result/error responses
+ */
+export class HubBridge {
+	/** @type {number} */
+	port
+
+	/** @type {http.Server} */
+	#httpServer
+
+	/** @type {WebSocketServer} */
+	#wss
+
+	/** @type {import('ws').WebSocket | null} */
+	#hub = null
+
+	/** @type {{ resolve: (r: {success: boolean, data: string}) => void, reject: (e: Error) => void } | null} */
+	#pendingTask = null
+
+	/** @param {number} port */
+	constructor(port) {
+		this.port = port
+		this.#httpServer = http.createServer((_req, res) => {
+			const html = launcherTemplate
+				.replaceAll('__EXT_ID__', EXT_ID)
+				.replaceAll('__STORE_URL__', STORE_URL)
+				.replaceAll('__WS_PORT__', String(port))
+			res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' })
+			res.end(html)
+		})
+		this.#wss = new WebSocketServer({ server: this.#httpServer })
+		this.#wss.on('connection', (ws) => this.#onConnection(ws))
+	}
+
+	/** @returns {Promise<void>} */
+	async start() {
+		return new Promise((resolve, reject) => {
+			this.#httpServer.on('error', (/** @type {NodeJS.ErrnoException} */ err) => {
+				if (err.code === 'EADDRINUSE') {
+					reject(
+						new Error(`Port ${this.port} is in use. Another Page Agent MCP server may be running.`)
+					)
+				} else {
+					reject(err)
+				}
+			})
+			this.#httpServer.listen(this.port, LOOPBACK_HOST, () => {
+				console.error(`[page-agent-mcp] HTTP + WS on http://${LOOPBACK_HOST}:${this.port}`)
+				resolve()
+			})
+		})
+	}
+
+	get connected() {
+		return this.#hub?.readyState === 1
+	}
+
+	get busy() {
+		return this.#pendingTask !== null
+	}
+
+	/**
+	 * @param {string} task
+	 * @param {Record<string, unknown>} [config]
+	 * @returns {Promise<{success: boolean, data: string}>}
+	 */
+	async executeTask(task, config) {
+		if (!this.connected) throw new Error('Hub is not connected. Is the extension running?')
+		if (this.#pendingTask) throw new Error('Agent is already running a task.')
+
+		return new Promise((resolve, reject) => {
+			this.#pendingTask = { resolve, reject }
+			this.#hub.send(JSON.stringify({ type: 'execute', task, config }))
+		})
+	}
+
+	stopTask() {
+		if (this.connected) {
+			this.#hub.send(JSON.stringify({ type: 'stop' }))
+		}
+	}
+
+	// TODO: Add version checking
+
+	/** @param {import('ws').WebSocket} ws */
+	#onConnection(ws) {
+		if (this.#hub && this.#hub.readyState === 1) {
+			ws.close(4000, 'Another hub is already connected')
+			return
+		}
+
+		this.#hub = ws
+		console.error('[page-agent-mcp] Hub connected')
+
+		ws.on('message', (/** @type {Buffer} */ rawData) => {
+			/** @type {{ type: string, success?: boolean, data?: string, message?: string }} */
+			let msg
+			try {
+				msg = JSON.parse(rawData.toString('utf-8'))
+			} catch {
+				return
+			}
+
+			if (msg.type === 'result') {
+				this.#pendingTask?.resolve({ success: msg.success ?? false, data: msg.data ?? '' })
+				this.#pendingTask = null
+			} else if (msg.type === 'error') {
+				this.#pendingTask?.reject(new Error(msg.message ?? 'Unknown error from hub'))
+				this.#pendingTask = null
+			}
+		})
+
+		ws.on('close', () => {
+			console.error('[page-agent-mcp] Hub disconnected')
+			if (this.#hub === ws) this.#hub = null
+			if (this.#pendingTask) {
+				this.#pendingTask.reject(new Error('Hub disconnected while task was running'))
+				this.#pendingTask = null
+			}
+		})
+	}
+}
diff --git a/packages/mcp/src/index.js b/packages/mcp/src/index.js
new file mode 100755
index 0000000..0f5482f
--- /dev/null
+++ b/packages/mcp/src/index.js
@@ -0,0 +1,100 @@
+#!/usr/bin/env node
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
+import { exec } from 'node:child_process'
+import { readFileSync } from 'node:fs'
+import { platform } from 'node:os'
+import * as z from 'zod/v4'
+
+import { HubBridge } from './hub-bridge.js'
+
+const env = process.env
+const port = parseInt(env.PORT || '38401')
+const { version } = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'))
+
+/** @type {Record<string, string>} */
+const llmConfig = {}
+if (env.LLM_BASE_URL) llmConfig.baseURL = env.LLM_BASE_URL
+if (env.LLM_MODEL_NAME) llmConfig.model = env.LLM_MODEL_NAME
+if (env.LLM_API_KEY) llmConfig.apiKey = env.LLM_API_KEY
+
+// --- Hub bridge (HTTP + WebSocket) ---
+
+const hub = new HubBridge(port)
+await hub.start()
+
+// Open launcher in default browser
+const url = `http://localhost:${port}`
+const cmd = platform() === 'darwin' ? 'open' : platform() === 'win32' ? 'start ""' : 'xdg-open'
+exec(`${cmd} "${url}"`, (err) => {
+	if (err) console.error(`[page-agent-mcp] Could not open browser: ${err.message}`)
+})
+
+// --- MCP server (stdio) ---
+
+const mcpServer = new McpServer({ name: 'page-agent', version })
+
+mcpServer.registerTool(
+	'execute_task',
+	{
+		description: "Execute a task in user's browser.",
+		inputSchema: {
+			task: z
+				.string()
+				.describe(
+					'Task description. Give specific instructions for the task. Steps preferable. And the information you want to get after the task is done.'
+				),
+		},
+	},
+	async ({ task }) => {
+		try {
+			const config = Object.keys(llmConfig).length > 0 ? llmConfig : undefined
+			const result = await hub.executeTask(task, config)
+			return {
+				content: [
+					{
+						type: 'text',
+						text: result.success
+							? `Task completed.\n\n${result.data}`
+							: `Task failed.\n\n${result.data}`,
+					},
+				],
+			}
+		} catch (err) {
+			return {
+				content: [{ type: 'text', text: `Error: ${err.message}` }],
+				isError: true,
+			}
+		}
+	}
+)
+
+mcpServer.registerTool(
+	'get_status',
+	{
+		description: 'Check the current status of the Page Agent hub.',
+	},
+	async () => ({
+		content: [
+			{
+				type: 'text',
+				text: JSON.stringify({ connected: hub.connected, busy: hub.busy }, null, 2),
+			},
+		],
+	})
+)
+
+mcpServer.registerTool(
+	'stop_task',
+	{
+		description: 'Stop the currently running browser automation task.',
+	},
+	async () => {
+		hub.stopTask()
+		return { content: [{ type: 'text', text: 'Stop signal sent.' }] }
+	}
+)
+
+const transport = new StdioServerTransport()
+await mcpServer.connect(transport)
+console.error('[page-agent-mcp] MCP server ready (stdio)')
diff --git a/packages/mcp/src/launcher.html b/packages/mcp/src/launcher.html
new file mode 100644
index 0000000..93fc221
--- /dev/null
+++ b/packages/mcp/src/launcher.html
@@ -0,0 +1,242 @@
+<!doctype html>
+<html>
+	<head>
+		<meta charset="UTF-8" />
+		<meta name="viewport" content="width=device-width, initial-scale=1.0" />
+		<link rel="icon" href="https://page-agent.github.io/assets/brand/page-agent-color-64.png" />
+		<title>Page Agent MCP Launcher</title>
+		<style>
+			* {
+				margin: 0;
+				padding: 0;
+				box-sizing: border-box;
+			}
+			body {
+				font-family:
+					system-ui,
+					-apple-system,
+					sans-serif;
+				background: #09090b;
+				color: #e5e5e5;
+				display: flex;
+				align-items: center;
+				justify-content: center;
+				min-height: 100vh;
+			}
+			.card {
+				text-align: center;
+				max-width: 480px;
+				padding: 3rem 2rem;
+			}
+			.logo {
+				width: 72px;
+				height: 72px;
+				border-radius: 18px;
+				margin-bottom: 1rem;
+			}
+			.badge {
+				font-size: 0.6875rem;
+				font-weight: 500;
+				color: #52525b;
+				letter-spacing: 0.05em;
+				text-transform: uppercase;
+				margin-bottom: 1.5rem;
+			}
+			h1 {
+				font-size: 1.35rem;
+				font-weight: 600;
+				margin-bottom: 0.5rem;
+			}
+			.sub {
+				font-size: 0.875rem;
+				color: #a1a1aa;
+				line-height: 1.7;
+			}
+			.spinner {
+				width: 32px;
+				height: 32px;
+				border: 3px solid #27272a;
+				border-top-color: #fff;
+				border-radius: 50%;
+				animation: spin 0.8s linear infinite;
+				margin: 0 auto 1.5rem;
+			}
+			@keyframes spin {
+				to {
+					transform: rotate(360deg);
+				}
+			}
+			a {
+				color: #60a5fa;
+				text-decoration: none;
+			}
+			a:hover {
+				text-decoration: underline;
+			}
+
+			.install {
+				display: none;
+			}
+			.install.show {
+				display: block;
+			}
+
+			.tips {
+				margin-top: 1.75rem;
+				text-align: left;
+				background: #18181b;
+				border: 1px solid #27272a;
+				border-radius: 12px;
+				padding: 1.25rem 1.5rem;
+			}
+			.tips li {
+				font-size: 0.8125rem;
+				color: #a1a1aa;
+				line-height: 1.7;
+				margin-left: 1rem;
+			}
+			.tips li + li {
+				margin-top: 0.35rem;
+			}
+
+			.store-btn {
+				display: inline-flex;
+				align-items: center;
+				gap: 0.625rem;
+				margin-top: 1.5rem;
+				padding: 0.625rem 1.5rem;
+				background: #2563eb;
+				color: #fff;
+				border-radius: 10px;
+				font-size: 0.875rem;
+				font-weight: 500;
+				transition: background 0.15s;
+			}
+			.store-btn:hover {
+				background: #1d4ed8;
+				text-decoration: none;
+			}
+			.store-btn img {
+				width: 20px;
+				height: 20px;
+			}
+
+			.links {
+				margin-top: 1.75rem;
+				display: flex;
+				justify-content: center;
+				gap: 1.5rem;
+				font-size: 0.8125rem;
+			}
+			.links a {
+				color: #71717a;
+				transition: color 0.15s;
+			}
+			.links a:hover {
+				color: #a1a1aa;
+				text-decoration: none;
+			}
+		</style>
+	</head>
+	<body>
+		<div class="card">
+			<img
+				class="logo"
+				src="https://page-agent.github.io/assets/brand/page-agent-color-512.webp"
+				alt="Page Agent"
+			/>
+			<div class="badge">Page Agent MCP Launcher</div>
+
+			<div id="connecting">
+				<div class="spinner"></div>
+				<h1 data-i18n="connecting_title">Connecting to Page Agent</h1>
+				<p class="sub" data-i18n="connecting_sub">Opening the hub in your browser…</p>
+			</div>
+
+			<div id="install" class="install">
+				<h1 data-i18n="install_title">Extension Required</h1>
+				<p class="sub" data-i18n="install_sub">
+					Page Agent requires the latest browser extension to work.
+				</p>
+
+				<a class="store-btn" href="__STORE_URL__" target="_blank">
+					<img
+						src="https://page-agent.github.io/assets/third-party/chrome-web-store-192.svg"
+						alt=""
+					/>
+					<span data-i18n="install_btn">Install from Chrome Web Store</span>
+				</a>
+
+				<ul class="tips">
+					<li data-i18n="tip_outdated">
+						If the extension is outdated, please update it to the latest version.
+					</li>
+					<li data-i18n="tip_other_browser">
+						If the extension is not installed in this browser, open this page from the browser that
+						has it installed.
+					</li>
+					<li data-i18n="tip_refresh">Refresh this page after installing or updating.</li>
+				</ul>
+			</div>
+
+			<div class="links">
+				<a
+					href="https://alibaba.github.io/page-agent/docs/introduction/overview"
+					target="_blank"
+					data-i18n="link_docs"
+					>Docs</a
+				>
+				<a
+					href="https://github.com/alibaba/page-agent/issues"
+					target="_blank"
+					data-i18n="link_issues"
+					>Report an Issue</a
+				>
+			</div>
+		</div>
+
+		<script>
+			{
+				const EXT_ID = '__EXT_ID__'
+				const wsPort = __WS_PORT__
+
+				const zh = {
+					connecting_title: '正在连接 Page Agent',
+					connecting_sub: '正在浏览器中打开 Hub…',
+					install_title: '需要安装浏览器插件',
+					install_sub: 'Page Agent 需要安装最新版浏览器插件才能运行。',
+					install_btn: '从 Chrome 应用商店安装',
+					tip_outdated: '如果插件版本过旧，请更新到最新版本。',
+					tip_other_browser: '如果该浏览器中未安装插件，请从装有插件的浏览器打开此页面。',
+					tip_refresh: '安装或更新后，请刷新此页面。',
+					link_docs: '文档',
+					link_issues: '问题反馈',
+				}
+
+				if (/^zh\b/i.test(navigator.language)) {
+					document.querySelectorAll('[data-i18n]').forEach((el) => {
+						const key = el.getAttribute('data-i18n')
+						if (zh[key]) el.textContent = zh[key]
+					})
+				}
+
+				const showInstall = () => {
+					document.getElementById('connecting').style.display = 'none'
+					document.getElementById('install').classList.add('show')
+				}
+
+				try {
+					if (!globalThis.chrome?.runtime?.sendMessage) {
+						showInstall()
+					} else {
+						chrome.runtime.sendMessage(EXT_ID, { type: 'OPEN_HUB', wsPort }, (response) => {
+							if (chrome.runtime.lastError || !response?.ok) showInstall()
+						})
+					}
+				} catch {
+					showInstall()
+				}
+			}
+		</script>
+	</body>
+</html>
diff --git a/packages/page-agent/package.json b/packages/page-agent/package.json
new file mode 100644
index 0000000..7cefc67
--- /dev/null
+++ b/packages/page-agent/package.json
@@ -0,0 +1,69 @@
+{
+    "name": "page-agent",
+    "private": false,
+    "version": "1.12.1",
+    "type": "module",
+    "main": "./src/PageAgent.ts",
+    "types": "./src/PageAgent.ts",
+    "exports": {
+        ".": {
+            "types": "./src/PageAgent.ts",
+            "default": "./src/PageAgent.ts"
+        }
+    },
+    "publishConfig": {
+        "main": "./dist/esm/page-agent.js",
+        "module": "./dist/esm/page-agent.js",
+        "types": "./dist/esm/PageAgent.d.ts",
+        "exports": {
+            ".": {
+                "types": "./dist/esm/PageAgent.d.ts",
+                "import": "./dist/esm/page-agent.js",
+                "default": "./dist/esm/page-agent.js"
+            }
+        }
+    },
+    "files": [
+        "dist/"
+    ],
+    "description": "GUI agent for web applications - add intelligent automation to any webpage with a single script",
+    "keywords": [
+        "ai",
+        "automation",
+        "ui-agent",
+        "GUI-agent",
+        "browser-automation",
+        "web-agent",
+        "llm",
+        "dom-interaction",
+        "web-automation",
+        "GUI-simulation"
+    ],
+    "author": "Simon<gaomeng1900>",
+    "license": "MIT",
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/alibaba/page-agent.git"
+    },
+    "homepage": "https://alibaba.github.io/page-agent/",
+    "scripts": {
+        "build": "vite build && npm run build:demo",
+        "build:demo": "vite build --config vite.iife.config.js",
+        "dev:demo": "concurrently \"vite build --config vite.iife.config.js --watch\" \"npx serve dist/iife -p 5174\"",
+        "prepublishOnly": "node ../../scripts/pre-publish.js",
+        "postpublish": "node ../../scripts/post-publish.js"
+    },
+    "dependencies": {
+        "@page-agent/core": "1.12.1",
+        "@page-agent/llms": "1.12.1",
+        "@page-agent/page-controller": "1.12.1",
+        "@page-agent/ui": "1.12.1",
+        "chalk": "^5.6.2"
+    },
+    "peerDependencies": {
+        "zod": "^3.25.0 || ^4.0.0"
+    },
+    "devDependencies": {
+        "zod": "^4.4.3"
+    }
+}
diff --git a/packages/page-agent/src/PageAgent.ts b/packages/page-agent/src/PageAgent.ts
new file mode 100644
index 0000000..486396b
--- /dev/null
+++ b/packages/page-agent/src/PageAgent.ts
@@ -0,0 +1,29 @@
+/**
+ * Copyright (C) 2025 Alibaba Group Holding Limited
+ * All rights reserved.
+ */
+import { type AgentConfig, PageAgentCore } from '@page-agent/core'
+import { PageController, type PageControllerConfig } from '@page-agent/page-controller'
+import { Panel, type PanelConfig } from '@page-agent/ui'
+
+export * from '@page-agent/core'
+
+export type PageAgentConfig = AgentConfig & PageControllerConfig & Omit<PanelConfig, 'language'>
+
+export class PageAgent extends PageAgentCore {
+	panel: Panel
+
+	constructor(config: PageAgentConfig) {
+		const pageController = new PageController({
+			...config,
+			enableMask: config.enableMask ?? true,
+		})
+
+		super({ ...config, pageController })
+
+		this.panel = new Panel(this, {
+			language: config.language,
+			promptForNextTask: config.promptForNextTask,
+		})
+	}
+}
diff --git a/packages/page-agent/src/demo.ts b/packages/page-agent/src/demo.ts
new file mode 100644
index 0000000..e15ba39
--- /dev/null
+++ b/packages/page-agent/src/demo.ts
@@ -0,0 +1,55 @@
+/**
+ * IIFE demo entry - auto-initializes with built-in demo API for testing
+ */
+import { PageAgent, type PageAgentConfig } from './PageAgent'
+
+const currentScript = document.currentScript as HTMLScriptElement | null
+const currentScriptURL = currentScript?.src ? new URL(currentScript.src) : null
+const autoInit = currentScriptURL?.searchParams.get('autoInit') !== 'false'
+
+// Clean up existing instances to prevent multiple injections from bookmarklet
+if (autoInit && window.pageAgent) {
+	window.pageAgent.dispose()
+}
+
+// Mount to global window object
+window.PageAgent = PageAgent
+
+console.log('🚀 page-agent.js loaded!')
+
+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
+if (autoInit) {
+	setTimeout(() => {
+		let config: PageAgentConfig
+		let showPanel = true
+
+		if (currentScriptURL) {
+			const url = currentScriptURL
+			const model = url.searchParams.get('model') || DEMO_MODEL
+			const baseURL = url.searchParams.get('baseURL') || DEMO_BASE_URL
+			const apiKey = url.searchParams.get('apiKey') || DEMO_API_KEY
+			const language = (url.searchParams.get('lang') as 'zh-CN' | 'en-US') || 'zh-CN'
+			showPanel = ((url.searchParams.get('showPanel') as 'true' | 'false') || 'true') === 'true'
+			config = { model, baseURL, apiKey, language }
+		} else {
+			console.log('🚀 page-agent.js no current script detected, using default demo config')
+			config = {
+				model: import.meta.env.LLM_MODEL_NAME ? import.meta.env.LLM_MODEL_NAME : DEMO_MODEL,
+				baseURL: import.meta.env.LLM_BASE_URL ? import.meta.env.LLM_BASE_URL : DEMO_BASE_URL,
+				apiKey: import.meta.env.LLM_API_KEY ? import.meta.env.LLM_API_KEY : DEMO_API_KEY,
+			}
+		}
+
+		// Create agent
+		window.pageAgent = new PageAgent(config)
+		if (showPanel) {
+			window.pageAgent.panel.show()
+		}
+
+		console.log('🚀 page-agent.js initialized with config:', window.pageAgent.config)
+	})
+}
diff --git a/packages/page-agent/src/env.d.ts b/packages/page-agent/src/env.d.ts
new file mode 100644
index 0000000..21d2cd5
--- /dev/null
+++ b/packages/page-agent/src/env.d.ts
@@ -0,0 +1,9 @@
+/// <reference types="vite/client" />
+import type { PageAgent } from './PageAgent'
+
+declare global {
+	interface Window {
+		pageAgent?: PageAgent
+		PageAgent: typeof PageAgent
+	}
+}
diff --git a/packages/page-agent/tsconfig.json b/packages/page-agent/tsconfig.json
new file mode 100644
index 0000000..d45abe9
--- /dev/null
+++ b/packages/page-agent/tsconfig.json
@@ -0,0 +1,8 @@
+{
+    "extends": "../../tsconfig.base.json",
+    "compilerOptions": {
+        "tsBuildInfoFile": "./node_modules/.tmp/tsconfig.tsbuildinfo"
+    },
+    "include": ["src/**/*.ts"],
+    "exclude": ["dist", "node_modules"]
+}
diff --git a/packages/page-agent/vite.config.js b/packages/page-agent/vite.config.js
new file mode 100644
index 0000000..2fa48ff
--- /dev/null
+++ b/packages/page-agent/vite.config.js
@@ -0,0 +1,52 @@
+// @ts-check
+import { dirname, resolve } from 'path'
+import dts from 'unplugin-dts/vite'
+import { fileURLToPath } from 'url'
+import { defineConfig } from 'vite'
+import cssInjectedByJsPlugin from 'vite-plugin-css-injected-by-js'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+
+// ES Module for NPM Package
+export default defineConfig({
+	clearScreen: false,
+	plugins: [
+		dts({
+			include: ['src/**/*.ts'],
+			exclude: ['src/**/*.test.ts'],
+			bundleTypes: true,
+			compilerOptions: {
+				composite: true,
+				noEmit: false,
+				emitDeclarationOnly: true,
+				declaration: true,
+			},
+		}),
+		cssInjectedByJsPlugin({ relativeCSSInjection: true }),
+	],
+	publicDir: false,
+	build: {
+		lib: {
+			entry: resolve(__dirname, 'src/PageAgent.ts'),
+			name: 'PageAgent',
+			fileName: 'page-agent',
+			formats: ['es'],
+		},
+		outDir: resolve(__dirname, 'dist', 'esm'),
+		rollupOptions: {
+			external: [
+				'chalk',
+				'zod',
+				'zod/v4',
+				// all the internal packages
+				/^@page-agent\//,
+			],
+		},
+		minify: false,
+		sourcemap: true,
+		cssCodeSplit: true,
+	},
+	define: {
+		'process.env.NODE_ENV': '"production"',
+	},
+})
diff --git a/packages/page-agent/vite.iife.config.js b/packages/page-agent/vite.iife.config.js
new file mode 100644
index 0000000..3b2100b
--- /dev/null
+++ b/packages/page-agent/vite.iife.config.js
@@ -0,0 +1,49 @@
+// @ts-check
+import { config as dotenvConfig } from 'dotenv'
+import { dirname, resolve } from 'path'
+import { fileURLToPath } from 'url'
+import { defineConfig } from 'vite'
+import cssInjectedByJsPlugin from 'vite-plugin-css-injected-by-js'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+
+// Load .env from repo root
+dotenvConfig({ path: resolve(__dirname, '../../.env'), quiet: true })
+
+// UMD Bundle for CDN
+// - alias all local packages so that they can be build in
+// - no external
+// - no d.ts. dts does not work with monorepo aliasing
+export default defineConfig(() => ({
+	plugins: [
+		cssInjectedByJsPlugin({ relativeCSSInjection: true }),
+		// analyzer()
+	],
+	publicDir: false,
+	build: {
+		lib: {
+			entry: resolve(__dirname, 'src/demo.ts'),
+			name: 'PageAgent',
+			fileName: () => `page-agent.demo.js`,
+			formats: ['iife'],
+		},
+		outDir: resolve(__dirname, 'dist', 'iife'),
+		cssCodeSplit: true,
+		// minify: false,
+		rollupOptions: {
+			// output: {
+			// 	// force use .js as extension
+			// 	entryFileNames: 'page-agent.js',
+			// },
+			onwarn: function (message, handler) {
+				if (message.code === 'EVAL') return
+				handler(message)
+			},
+		},
+	},
+	define: {
+		'import.meta.env.LLM_MODEL_NAME': JSON.stringify(process.env.LLM_MODEL_NAME),
+		'import.meta.env.LLM_API_KEY': JSON.stringify(process.env.LLM_API_KEY),
+		'import.meta.env.LLM_BASE_URL': JSON.stringify(process.env.LLM_BASE_URL),
+	},
+}))
diff --git a/packages/page-controller/package.json b/packages/page-controller/package.json
new file mode 100644
index 0000000..ef1520b
--- /dev/null
+++ b/packages/page-controller/package.json
@@ -0,0 +1,52 @@
+{
+    "name": "@page-agent/page-controller",
+    "version": "1.12.1",
+    "type": "module",
+    "main": "./src/PageController.ts",
+    "types": "./src/PageController.ts",
+    "exports": {
+        ".": {
+            "types": "./src/PageController.ts",
+            "default": "./src/PageController.ts"
+        }
+    },
+    "publishConfig": {
+        "main": "./dist/lib/page-controller.js",
+        "module": "./dist/lib/page-controller.js",
+        "types": "./dist/lib/PageController.d.ts",
+        "exports": {
+            ".": {
+                "types": "./dist/lib/PageController.d.ts",
+                "import": "./dist/lib/page-controller.js",
+                "default": "./dist/lib/page-controller.js"
+            }
+        }
+    },
+    "files": [
+        "dist/"
+    ],
+    "description": "Page controller for page-agent - DOM operations and element interactions",
+    "keywords": [
+        "page-agent",
+        "dom",
+        "browser-automation",
+        "web-automation"
+    ],
+    "author": "Simon<gaomeng1900>",
+    "license": "MIT",
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/alibaba/page-agent.git",
+        "directory": "packages/page-controller"
+    },
+    "homepage": "https://alibaba.github.io/page-agent/",
+    "scripts": {
+        "build": "vite build",
+        "test": "vitest run",
+        "prepublishOnly": "node ../../scripts/pre-publish.js",
+        "postpublish": "node ../../scripts/post-publish.js"
+    },
+    "dependencies": {
+        "ai-motion": "^0.4.8"
+    }
+}
diff --git a/packages/page-controller/src/PageController.test.ts b/packages/page-controller/src/PageController.test.ts
new file mode 100644
index 0000000..122d6ec
--- /dev/null
+++ b/packages/page-controller/src/PageController.test.ts
@@ -0,0 +1,40 @@
+import { describe, expect, it } from 'vitest'
+
+import { PageController } from './PageController'
+
+describe('PageController', () => {
+	it('constructs and exposes the current url', async () => {
+		const controller = new PageController()
+		expect(controller).toBeInstanceOf(PageController)
+		expect(await controller.getCurrentUrl()).toBe(window.location.href)
+	})
+
+	describe('executeJavascript', () => {
+		it('runs a script and returns its result', async () => {
+			const controller = new PageController()
+			const result = await controller.executeJavascript('return 1 + 2')
+			expect(result).toMatchObject({ success: true })
+			expect(result.message).toContain('3')
+		})
+
+		it('exposes the abort signal to the script scope', async () => {
+			const controller = new PageController()
+			const controllerSignal = new AbortController()
+			controllerSignal.abort()
+
+			const result = await controller.executeJavascript(
+				'return signal.aborted',
+				controllerSignal.signal
+			)
+			expect(result).toMatchObject({ success: true })
+			expect(result.message).toContain('true')
+		})
+
+		it('reports a syntax error as a failed result', async () => {
+			const controller = new PageController()
+			const result = await controller.executeJavascript('return (')
+			expect(result.success).toBe(false)
+			expect(result.message).toContain('❌')
+		})
+	})
+})
diff --git a/packages/page-controller/src/PageController.ts b/packages/page-controller/src/PageController.ts
new file mode 100644
index 0000000..ad93528
--- /dev/null
+++ b/packages/page-controller/src/PageController.ts
@@ -0,0 +1,435 @@
+/**
+ * Copyright (C) 2025 Alibaba Group Holding Limited
+ * All rights reserved.
+ *
+ * PageController - Manages DOM operations and element interactions.
+ * Designed to be independent of LLM and can be tested in unit tests.
+ * All public methods are async for potential remote calling support.
+ */
+import {
+	clickElement,
+	getElementByIndex,
+	inputTextElement,
+	scrollHorizontally,
+	scrollVertically,
+	selectOptionElement,
+} from './actions'
+import * as dom from './dom'
+import type { FlatDomTree, InteractiveElementDomNode } from './dom/dom_tree/type'
+import { getPageInfo } from './dom/getPageInfo'
+import { patchReact } from './patches/react'
+import { isAnchorElement } from './utils'
+
+/**
+ * Configuration for PageController
+ */
+export interface PageControllerConfig extends dom.DomConfig {
+	/** Enable visual mask overlay during operations (default: false) */
+	enableMask?: boolean
+}
+
+/**
+ * Structured browser state for LLM consumption
+ */
+export interface BrowserState {
+	url: string
+	title: string
+	/** Page info + scroll position hint (e.g. "Page info: 1920x1080px...\n[Start of page]") */
+	header: string
+	/** Simplified HTML of interactive elements */
+	content: string
+	/** Page footer hint (e.g. "... 300 pixels below ..." or "[End of page]") */
+	footer: string
+}
+
+interface ActionResult {
+	success: boolean
+	message: string
+}
+
+/**
+ * PageController manages DOM state and element interactions.
+ * It provides async methods for all DOM operations, keeping state isolated.
+ *
+ * @lifecycle
+ * - beforeUpdate: Emitted before the DOM tree is updated.
+ * - afterUpdate: Emitted after the DOM tree is updated.
+ */
+export class PageController extends EventTarget {
+	private config: PageControllerConfig
+
+	/** Corresponds to eval_page in browser-use */
+	private flatTree: FlatDomTree | null = null
+
+	/**
+	 * All highlighted index-mapped interactive elements
+	 * Corresponds to DOMState.selector_map in browser-use
+	 */
+	private selectorMap = new Map<number, InteractiveElementDomNode>()
+
+	/** Index -> element text description mapping */
+	private elementTextMap = new Map<number, string>()
+
+	/**
+	 * Simplified HTML for LLM consumption.
+	 * Corresponds to clickable_elements_to_string in browser-use
+	 */
+	private simplifiedHTML = '<EMPTY>'
+
+	/** last time the tree was updated */
+	private lastTimeUpdate = 0
+
+	/** Whether the tree has been indexed at least once */
+	private isIndexed = false
+
+	/** Visual mask overlay for blocking user interaction during automation */
+	private mask: InstanceType<typeof import('./mask/SimulatorMask').SimulatorMask> | null = null
+	private maskReady: Promise<void> | null = null
+
+	constructor(config: PageControllerConfig = {}) {
+		super()
+
+		this.config = config
+
+		patchReact(this)
+
+		if (config.enableMask) this.initMask()
+	}
+
+	/**
+	 * Initialize mask asynchronously (dynamic import to avoid CSS loading in Node)
+	 */
+	initMask() {
+		if (this.maskReady !== null) return
+		this.maskReady = (async () => {
+			const { SimulatorMask } = await import('./mask/SimulatorMask')
+			this.mask = new SimulatorMask()
+		})()
+	}
+	// ======= State Queries =======
+
+	/**
+	 * Get current page URL
+	 */
+	async getCurrentUrl(): Promise<string> {
+		return window.location.href
+	}
+
+	/**
+	 * Get last tree update timestamp
+	 */
+	async getLastUpdateTime(): Promise<number> {
+		return this.lastTimeUpdate
+	}
+
+	/**
+	 * Get structured browser state for LLM consumption.
+	 * Automatically calls updateTree() to refresh the DOM state.
+	 */
+	async getBrowserState(): Promise<BrowserState> {
+		const url = window.location.href
+		const title = document.title
+		const pi = getPageInfo()
+		const viewportExpansion = dom.resolveViewportExpansion(this.config.viewportExpansion)
+
+		await this.updateTree()
+
+		const content = this.simplifiedHTML
+
+		// Build header: page info + scroll position hint
+		const titleLine = `Current Page: [${title}](${url})`
+
+		const pageInfoLine = `Page info: ${pi.viewport_width}x${pi.viewport_height}px viewport, ${pi.page_width}x${pi.page_height}px total page size, ${pi.pages_above.toFixed(1)} pages above, ${pi.pages_below.toFixed(1)} pages below, ${pi.total_pages.toFixed(1)} total pages, at ${(pi.current_page_position * 100).toFixed(0)}% of page`
+
+		const elementsLabel =
+			viewportExpansion === -1
+				? 'Interactive elements from top layer of the current page (full page):'
+				: 'Interactive elements from top layer of the current page inside the viewport:'
+
+		const hasContentAbove = pi.pixels_above > 4
+		const scrollHintAbove =
+			hasContentAbove && viewportExpansion !== -1
+				? `... ${pi.pixels_above} pixels above (${pi.pages_above.toFixed(1)} pages) - scroll to see more ...`
+				: '[Start of page]'
+
+		const header = `${titleLine}\n${pageInfoLine}\n\n${elementsLabel}\n\n${scrollHintAbove}`
+
+		// Build footer: scroll position hint
+		const hasContentBelow = pi.pixels_below > 4
+		const footer =
+			hasContentBelow && viewportExpansion !== -1
+				? `... ${pi.pixels_below} pixels below (${pi.pages_below.toFixed(1)} pages) - scroll to see more ...`
+				: '[End of page]'
+
+		return { url, title, header, content, footer }
+	}
+
+	// ======= DOM Tree Operations =======
+
+	/**
+	 * Update DOM tree, returns simplified HTML for LLM.
+	 * This is the main method to refresh the page state.
+	 * Automatically bypasses mask during DOM extraction if enabled.
+	 */
+	async updateTree(): Promise<string> {
+		this.dispatchEvent(new Event('beforeUpdate'))
+
+		this.lastTimeUpdate = Date.now()
+
+		// Temporarily bypass mask to allow DOM extraction
+		if (this.mask) {
+			this.mask.wrapper.style.pointerEvents = 'none'
+		}
+
+		dom.cleanUpHighlights()
+
+		const blacklist = [
+			...(this.config.interactiveBlacklist || []),
+			...Array.from(document.querySelectorAll('[data-page-agent-not-interactive]')),
+		]
+
+		this.flatTree = dom.getFlatTree({
+			...this.config,
+			interactiveBlacklist: blacklist,
+		})
+
+		this.simplifiedHTML = dom.flatTreeToString(
+			this.flatTree,
+			this.config.includeAttributes,
+			this.config.keepSemanticTags
+		)
+
+		this.selectorMap.clear()
+		this.selectorMap = dom.getSelectorMap(this.flatTree)
+
+		this.elementTextMap.clear()
+		this.elementTextMap = dom.getElementTextMap(this.simplifiedHTML)
+
+		// Mark as indexed - now element actions are allowed
+		this.isIndexed = true
+
+		// Restore mask blocking
+		if (this.mask) {
+			this.mask.wrapper.style.pointerEvents = 'auto'
+		}
+
+		this.dispatchEvent(new Event('afterUpdate'))
+
+		return this.simplifiedHTML
+	}
+
+	/**
+	 * Clean up all element highlights
+	 */
+	async cleanUpHighlights(): Promise<void> {
+		console.log('[PageController] cleanUpHighlights')
+		dom.cleanUpHighlights()
+	}
+
+	// ======= Element Actions =======
+
+	/**
+	 * Ensure the tree has been indexed before any index-based operation.
+	 * Throws if updateTree() hasn't been called yet.
+	 */
+	private assertIndexed(): void {
+		if (!this.isIndexed) {
+			throw new Error('DOM tree not indexed yet. Can not perform actions on elements.')
+		}
+	}
+
+	/**
+	 * Click element by index
+	 */
+	async clickElement(index: number): Promise<ActionResult> {
+		try {
+			this.assertIndexed()
+			const element = getElementByIndex(this.selectorMap, index)
+			const elemText = this.elementTextMap.get(index)
+			await clickElement(element)
+
+			// Handle links that open in new tabs
+			if (isAnchorElement(element) && element.target === '_blank') {
+				return {
+					success: true,
+					message: `✅ Clicked element (${elemText ?? index}). ⚠️ Link opened in a new tab.`,
+				}
+			}
+
+			return {
+				success: true,
+				message: `✅ Clicked element (${elemText ?? index}).`,
+			}
+		} catch (error) {
+			return {
+				success: false,
+				message: `❌ Failed to click element: ${error}`,
+			}
+		}
+	}
+
+	/**
+	 * Input text into element by index
+	 */
+	async inputText(index: number, text: string): Promise<ActionResult> {
+		try {
+			this.assertIndexed()
+			const element = getElementByIndex(this.selectorMap, index)
+			const elemText = this.elementTextMap.get(index)
+			await inputTextElement(element, text)
+
+			return {
+				success: true,
+				message: `✅ Input text (${text}) into element (${elemText ?? index}).`,
+			}
+		} catch (error) {
+			return {
+				success: false,
+				message: `❌ Failed to input text: ${error}`,
+			}
+		}
+	}
+
+	/**
+	 * Select dropdown option by index and option text
+	 */
+	async selectOption(index: number, optionText: string): Promise<ActionResult> {
+		try {
+			this.assertIndexed()
+			const element = getElementByIndex(this.selectorMap, index)
+			const elemText = this.elementTextMap.get(index)
+			await selectOptionElement(element as HTMLSelectElement, optionText)
+
+			return {
+				success: true,
+				message: `✅ Selected option (${optionText}) in element (${elemText ?? index}).`,
+			}
+		} catch (error) {
+			return {
+				success: false,
+				message: `❌ Failed to select option: ${error}`,
+			}
+		}
+	}
+
+	/**
+	 * Scroll vertically
+	 */
+	async scroll(options: {
+		down: boolean
+		numPages: number
+		pixels?: number
+		index?: number
+	}): Promise<ActionResult> {
+		try {
+			const { down, numPages, pixels, index } = options
+
+			this.assertIndexed()
+
+			const scrollAmount = (pixels ?? numPages * window.innerHeight) * (down ? 1 : -1)
+
+			const element = index !== undefined ? getElementByIndex(this.selectorMap, index) : null
+
+			const message = await scrollVertically(scrollAmount, element)
+
+			return {
+				success: true,
+				message,
+			}
+		} catch (error) {
+			return {
+				success: false,
+				message: `❌ Failed to scroll: ${error}`,
+			}
+		}
+	}
+
+	/**
+	 * Scroll horizontally
+	 */
+	async scrollHorizontally(options: {
+		right: boolean
+		pixels: number
+		index?: number
+	}): Promise<ActionResult> {
+		try {
+			const { right, pixels, index } = options
+
+			this.assertIndexed()
+
+			const scrollAmount = pixels * (right ? 1 : -1)
+
+			const element = index !== undefined ? getElementByIndex(this.selectorMap, index) : null
+
+			const message = await scrollHorizontally(scrollAmount, element)
+
+			return {
+				success: true,
+				message,
+			}
+		} catch (error) {
+			return {
+				success: false,
+				message: `❌ Failed to scroll horizontally: ${error}`,
+			}
+		}
+	}
+
+	/**
+	 * Execute arbitrary JavaScript on the page.
+	 * The optional `signal` is exposed to the script scope so cooperative code
+	 * can abort promptly when the task is stopped.
+	 */
+	async executeJavascript(script: string, signal?: AbortSignal): Promise<ActionResult> {
+		try {
+			// Wrap script in async function to support await, exposing `signal`.
+			const asyncFunction = eval(`(async (signal) => { ${script} })`)
+			const result = await asyncFunction(signal)
+			return {
+				success: true,
+				message: `✅ Executed JavaScript. Result: ${result}`,
+			}
+		} catch (error) {
+			return {
+				success: false,
+				message: `❌ Error executing JavaScript: ${error}`,
+			}
+		}
+	}
+
+	// ======= Mask Operations =======
+
+	/**
+	 * Show the visual mask overlay.
+	 * Only works after mask is setup.
+	 */
+	async showMask(): Promise<void> {
+		await this.maskReady
+		this.mask?.show()
+	}
+
+	/**
+	 * Hide the visual mask overlay.
+	 * Only works after mask is setup.
+	 */
+	async hideMask(): Promise<void> {
+		await this.maskReady
+		this.mask?.hide()
+	}
+
+	/**
+	 * Dispose and clean up resources
+	 */
+	dispose(): void {
+		dom.cleanUpHighlights()
+		this.flatTree = null
+		this.selectorMap.clear()
+		this.elementTextMap.clear()
+		this.simplifiedHTML = '<EMPTY>'
+		this.isIndexed = false
+		this.mask?.dispose()
+		this.mask = null
+	}
+}
+
+export * from './actions'
diff --git a/packages/page-controller/src/actions.ts b/packages/page-controller/src/actions.ts
new file mode 100644
index 0000000..e90326e
--- /dev/null
+++ b/packages/page-controller/src/actions.ts
@@ -0,0 +1,554 @@
+/**
+ * Copyright (C) 2025 Alibaba Group Holding Limited
+ * All rights reserved.
+ */
+import type { InteractiveElementDomNode } from './dom/dom_tree/type'
+import {
+	clickPointer,
+	disablePassThrough,
+	enablePassThrough,
+	getNativeValueSetter,
+	isHTMLElement,
+	isInputElement,
+	isSelectElement,
+	isTextAreaElement,
+	movePointerToElement,
+	waitFor,
+} from './utils'
+
+/**
+ * Get the HTMLElement by index from a selectorMap.
+ * @private Internal method, subject to change at any time.
+ */
+export function getElementByIndex(
+	selectorMap: Map<number, InteractiveElementDomNode>,
+	index: number
+): HTMLElement {
+	const interactiveNode = selectorMap.get(index)
+	if (!interactiveNode) {
+		throw new Error(`No interactive element found at index ${index}`)
+	}
+
+	const element = interactiveNode.ref
+	if (!element) {
+		throw new Error(`Element at index ${index} does not have a reference`)
+	}
+
+	if (!isHTMLElement(element)) {
+		throw new Error(`Element at index ${index} is not an HTMLElement`)
+	}
+
+	return element
+}
+
+let lastClickedElement: HTMLElement | null = null
+
+function blurLastClickedElement() {
+	if (lastClickedElement) {
+		lastClickedElement.dispatchEvent(new PointerEvent('pointerout', { bubbles: true }))
+		lastClickedElement.dispatchEvent(new PointerEvent('pointerleave', { bubbles: false }))
+		lastClickedElement.dispatchEvent(new MouseEvent('mouseout', { bubbles: true }))
+		lastClickedElement.dispatchEvent(new MouseEvent('mouseleave', { bubbles: false }))
+		lastClickedElement.blur()
+		lastClickedElement = null
+	}
+}
+
+/**
+ * Simulate a full click following W3C Pointer Events + UI Events spec order:
+ * pointerover/enter → mouseover/enter → pointerdown → mousedown → [focus] →
+ * pointerup → mouseup → click
+ *
+ * @private Internal method, subject to change at any time.
+ */
+export async function clickElement(element: HTMLElement) {
+	blurLastClickedElement()
+
+	lastClickedElement = element
+
+	await scrollIntoViewIfNeeded(element)
+	const frame = element.ownerDocument.defaultView?.frameElement
+	if (frame) await scrollIntoViewIfNeeded(frame)
+
+	const rect = element.getBoundingClientRect()
+	const x = rect.left + rect.width / 2
+	const y = rect.top + rect.height / 2
+
+	await movePointerToElement(element, x, y)
+	await clickPointer()
+
+	await waitFor(0.1)
+
+	// Hit-test to find the deepest element at click coordinates, matching
+	// real browser behavior where events target the innermost element.
+	// @note This may hit a element in the blacklist
+	// TODO: This is a temporary workaround. Should have been handled during dom extraction.
+	const doc = element.ownerDocument
+	await enablePassThrough()
+	const hitTarget = doc.elementFromPoint(x, y)
+	await disablePassThrough()
+	const target =
+		hitTarget instanceof HTMLElement && element.contains(hitTarget) ? hitTarget : element
+
+	const pointerOpts = {
+		bubbles: true,
+		cancelable: true,
+		clientX: x,
+		clientY: y,
+		pointerType: 'mouse',
+	}
+	const mouseOpts = { bubbles: true, cancelable: true, clientX: x, clientY: y, button: 0 }
+
+	// Hover — pointer events first, then mouse events (spec order)
+	target.dispatchEvent(new PointerEvent('pointerover', pointerOpts))
+	target.dispatchEvent(new PointerEvent('pointerenter', { ...pointerOpts, bubbles: false }))
+	target.dispatchEvent(new MouseEvent('mouseover', mouseOpts))
+	target.dispatchEvent(new MouseEvent('mouseenter', { ...mouseOpts, bubbles: false }))
+
+	// Press
+	target.dispatchEvent(new PointerEvent('pointerdown', pointerOpts))
+	target.dispatchEvent(new MouseEvent('mousedown', mouseOpts))
+
+	// Focus is not part of the standard pointer/mouse event sequence
+	// "undefined and varies between user agents".
+	// We focus the original element (nearest focusable ancestor), not the hit-test target, matching browser behavior.
+	element.focus({ preventScroll: true })
+
+	// Release
+	target.dispatchEvent(new PointerEvent('pointerup', pointerOpts))
+	target.dispatchEvent(new MouseEvent('mouseup', mouseOpts))
+
+	// Click — activation behavior (navigation, form submit, etc.) triggers
+	// via bubbling from target up to the interactive ancestor.
+	target.click()
+
+	await waitFor(0.2)
+}
+
+/**
+ * @private Internal method, subject to change at any time.
+ */
+export async function inputTextElement(element: HTMLElement, text: string) {
+	const isContentEditable = element.isContentEditable
+	if (!isInputElement(element) && !isTextAreaElement(element) && !isContentEditable) {
+		throw new Error('Element is not an input, textarea, or contenteditable')
+	}
+
+	await clickElement(element)
+
+	if (isContentEditable) {
+		// Contenteditable support (partial)
+		// Not supported:
+		// - Monaco/CodeMirror: Require direct JS instance access. No universal way to obtain.
+		// - Draft.js: Not responsive to synthetic/execCommand/Range/DataTransfer. Unmaintained.
+		//
+		// Strategy: Try Plan A (synthetic events) first, then verify and fall back
+		// to Plan B (execCommand) if the text wasn't actually inserted.
+		//
+		// Plan A: Dispatch synthetic events
+		// Works: React contenteditable, Quill.
+		// Fails: Slate.js, some contenteditable editors that ignore synthetic events.
+		// Sequence: beforeinput -> mutation -> input -> change -> blur
+
+		// Dispatch beforeinput + mutation + input for clearing
+		if (
+			element.dispatchEvent(
+				new InputEvent('beforeinput', {
+					bubbles: true,
+					cancelable: true,
+					inputType: 'deleteContent',
+				})
+			)
+		) {
+			element.innerText = ''
+			element.dispatchEvent(
+				new InputEvent('input', {
+					bubbles: true,
+					inputType: 'deleteContent',
+				})
+			)
+		}
+
+		// Dispatch beforeinput + mutation + input for insertion (important for React apps)
+		if (
+			element.dispatchEvent(
+				new InputEvent('beforeinput', {
+					bubbles: true,
+					cancelable: true,
+					inputType: 'insertText',
+					data: text,
+				})
+			)
+		) {
+			element.innerText = text
+			element.dispatchEvent(
+				new InputEvent('input', {
+					bubbles: true,
+					inputType: 'insertText',
+					data: text,
+				})
+			)
+		}
+
+		// Verify Plan A worked by checking if the text was actually inserted
+		const planASucceeded = element.innerText.trim() === text.trim()
+
+		if (!planASucceeded) {
+			// Plan B: execCommand fallback (deprecated but widely supported)
+			// Works: Quill, Slate.js, react contenteditable components.
+			// This approach integrates with the browser's undo stack and is handled
+			// natively by most rich-text editors.
+			element.focus()
+
+			// Select all existing content and delete it
+			const doc = element.ownerDocument
+			const selection = (doc.defaultView || window).getSelection()
+			const range = doc.createRange()
+			range.selectNodeContents(element)
+			selection?.removeAllRanges()
+			selection?.addRange(range)
+
+			doc.execCommand('delete', false)
+			doc.execCommand('insertText', false, text)
+		}
+
+		// Dispatch change event (for good measure)
+		element.dispatchEvent(new Event('change', { bubbles: true }))
+
+		// Trigger blur for validation
+		element.blur()
+	} else {
+		getNativeValueSetter(element as HTMLInputElement | HTMLTextAreaElement).call(element, text)
+	}
+
+	// Only dispatch shared input event for non-contenteditable (contenteditable has its own)
+	if (!isContentEditable) {
+		element.dispatchEvent(new Event('input', { bubbles: true }))
+	}
+
+	await waitFor(0.1)
+
+	blurLastClickedElement()
+}
+
+/**
+ * @todo browser-use version is very complex and supports menu tags, need to follow up
+ * @private Internal method, subject to change at any time.
+ */
+export async function selectOptionElement(selectElement: HTMLSelectElement, optionText: string) {
+	if (!isSelectElement(selectElement)) {
+		throw new Error('Element is not a select element')
+	}
+
+	const options = Array.from(selectElement.options)
+	const option = options.find((opt) => opt.textContent?.trim() === optionText.trim())
+
+	if (!option) {
+		throw new Error(`Option with text "${optionText}" not found in select element`)
+	}
+
+	selectElement.value = option.value
+	selectElement.dispatchEvent(new Event('change', { bubbles: true }))
+
+	await waitFor(0.1) // Wait to ensure change event processing completes
+}
+
+interface ScrollableElement extends Element {
+	scrollIntoViewIfNeeded?: (centerIfNeeded?: boolean) => void
+}
+
+/**
+ * @private Internal method, subject to change at any time.
+ */
+export async function scrollIntoViewIfNeeded(element: Element) {
+	const el = element as ScrollableElement
+	if (typeof el.scrollIntoViewIfNeeded === 'function') {
+		el.scrollIntoViewIfNeeded()
+		// await waitFor(0.5) // Animation playback
+	} else {
+		// @todo visibility check
+		element.scrollIntoView({ behavior: 'auto', block: 'center', inline: 'nearest' })
+		// await waitFor(0.5) // Animation playback
+	}
+}
+
+export async function scrollVertically(scroll_amount: number, element?: HTMLElement | null) {
+	// Element-specific scrolling if element is provided
+	if (element) {
+		const targetElement = element
+		let currentElement = targetElement as HTMLElement | null
+		let scrollSuccess = false
+		let scrolledElement: HTMLElement | null = null
+		let scrollDelta = 0
+		let attempts = 0
+		const dy = scroll_amount
+
+		while (currentElement && attempts < 10) {
+			const computedStyle = window.getComputedStyle(currentElement)
+			const hasScrollableY =
+				/(auto|scroll|overlay)/.test(computedStyle.overflowY) ||
+				(computedStyle.scrollbarWidth && computedStyle.scrollbarWidth !== 'auto') ||
+				(computedStyle.scrollbarGutter && computedStyle.scrollbarGutter !== 'auto')
+			const canScrollVertically = currentElement.scrollHeight > currentElement.clientHeight
+
+			if (hasScrollableY && canScrollVertically) {
+				const beforeScroll = currentElement.scrollTop
+				const maxScroll = currentElement.scrollHeight - currentElement.clientHeight
+
+				let scrollAmount = dy / 3
+
+				if (scrollAmount > 0) {
+					scrollAmount = Math.min(scrollAmount, maxScroll - beforeScroll)
+				} else {
+					scrollAmount = Math.max(scrollAmount, -beforeScroll)
+				}
+
+				currentElement.scrollTop = beforeScroll + scrollAmount
+
+				const afterScroll = currentElement.scrollTop
+				const actualScrollDelta = afterScroll - beforeScroll
+
+				if (Math.abs(actualScrollDelta) > 0.5) {
+					scrollSuccess = true
+					scrolledElement = currentElement
+					scrollDelta = actualScrollDelta
+					break
+				}
+			}
+
+			if (currentElement === document.body || currentElement === document.documentElement) {
+				break
+			}
+			currentElement = currentElement.parentElement
+			attempts++
+		}
+
+		if (scrollSuccess) {
+			return `Scrolled container (${scrolledElement?.tagName}) by ${scrollDelta}px`
+		} else {
+			return `No scrollable container found for element (${targetElement.tagName})`
+		}
+	}
+
+	// Page-level scrolling (default or fallback)
+
+	const dy = scroll_amount
+	const bigEnough = (el: HTMLElement) => el.clientHeight >= window.innerHeight * 0.5
+	const canScroll = (el: HTMLElement | null): boolean =>
+		Boolean(
+			el &&
+			/(auto|scroll|overlay)/.test(getComputedStyle(el).overflowY) &&
+			el.scrollHeight > el.clientHeight &&
+			bigEnough(el)
+		)
+
+	// @deprecated Heuristic container search.
+	// Unreliable in multi-panel layouts. Should guide LLMs to use indexed scroll for consistency.
+	// TODO: remove this fallback
+
+	// try to find the nearest scrollable container
+	// document.activeElement is usually body.
+	// After a successful element.focus(), activeElement become the nearest focusable parent
+
+	let el: HTMLElement | null = document.activeElement as HTMLElement | null
+	while (el && !canScroll(el) && el !== document.body) el = el.parentElement
+
+	// Something is wrong if it falls back to global '*' search
+	// TODO: Return error message instead of global '*' search
+
+	el = canScroll(el)
+		? el
+		: Array.from(document.querySelectorAll<HTMLElement>('*')).find(canScroll) ||
+			(document.scrollingElement as HTMLElement) ||
+			(document.documentElement as HTMLElement)
+
+	if (el === document.scrollingElement || el === document.documentElement || el === document.body) {
+		// Page-level scroll
+		const scrollBefore = window.scrollY
+		const scrollMax = document.documentElement.scrollHeight - window.innerHeight
+
+		window.scrollBy(0, dy)
+
+		const scrollAfter = window.scrollY
+		const scrolled = scrollAfter - scrollBefore
+
+		if (Math.abs(scrolled) < 1) {
+			return dy > 0
+				? `⚠️ Already at the bottom of the page, cannot scroll down further.`
+				: `⚠️ Already at the top of the page, cannot scroll up further.`
+		}
+
+		const reachedBottom = dy > 0 && scrollAfter >= scrollMax - 1
+		const reachedTop = dy < 0 && scrollAfter <= 1
+
+		if (reachedBottom) return `✅ Scrolled page by ${scrolled}px. Reached the bottom of the page.`
+		if (reachedTop) return `✅ Scrolled page by ${scrolled}px. Reached the top of the page.`
+		return `✅ Scrolled page by ${scrolled}px.`
+	} else {
+		// Container scroll
+
+		const warningMsg = `The document is not scrollable. Falling back to container scroll.`
+		console.log(`[PageController] ${warningMsg}`)
+
+		const scrollBefore = el!.scrollTop
+		const scrollMax = el!.scrollHeight - el!.clientHeight
+
+		el!.scrollBy({ top: dy, behavior: 'smooth' })
+		await waitFor(0.1)
+
+		const scrollAfter = el!.scrollTop
+		const scrolled = scrollAfter - scrollBefore
+
+		if (Math.abs(scrolled) < 1) {
+			return dy > 0
+				? `⚠️ ${warningMsg} Already at the bottom of container (${el!.tagName}), cannot scroll down further.`
+				: `⚠️ ${warningMsg} Already at the top of container (${el!.tagName}), cannot scroll up further.`
+		}
+
+		const reachedBottom = dy > 0 && scrollAfter >= scrollMax - 1
+		const reachedTop = dy < 0 && scrollAfter <= 1
+
+		if (reachedBottom)
+			return `✅ ${warningMsg} Scrolled container (${el!.tagName}) by ${scrolled}px. Reached the bottom.`
+		if (reachedTop)
+			return `✅ ${warningMsg} Scrolled container (${el!.tagName}) by ${scrolled}px. Reached the top.`
+		return `✅ ${warningMsg} Scrolled container (${el!.tagName}) by ${scrolled}px.`
+	}
+}
+
+export async function scrollHorizontally(scroll_amount: number, element?: HTMLElement | null) {
+	// Element-specific scrolling if element is provided
+	if (element) {
+		const targetElement = element
+		let currentElement = targetElement as HTMLElement | null
+		let scrollSuccess = false
+		let scrolledElement: HTMLElement | null = null
+		let scrollDelta = 0
+		let attempts = 0
+		const dx = scroll_amount
+
+		while (currentElement && attempts < 10) {
+			const computedStyle = window.getComputedStyle(currentElement)
+			const hasScrollableX =
+				/(auto|scroll|overlay)/.test(computedStyle.overflowX) ||
+				(computedStyle.scrollbarWidth && computedStyle.scrollbarWidth !== 'auto') ||
+				(computedStyle.scrollbarGutter && computedStyle.scrollbarGutter !== 'auto')
+			const canScrollHorizontally = currentElement.scrollWidth > currentElement.clientWidth
+
+			if (hasScrollableX && canScrollHorizontally) {
+				const beforeScroll = currentElement.scrollLeft
+				const maxScroll = currentElement.scrollWidth - currentElement.clientWidth
+
+				let scrollAmount = dx / 3
+
+				if (scrollAmount > 0) {
+					scrollAmount = Math.min(scrollAmount, maxScroll - beforeScroll)
+				} else {
+					scrollAmount = Math.max(scrollAmount, -beforeScroll)
+				}
+
+				currentElement.scrollLeft = beforeScroll + scrollAmount
+
+				const afterScroll = currentElement.scrollLeft
+				const actualScrollDelta = afterScroll - beforeScroll
+
+				if (Math.abs(actualScrollDelta) > 0.5) {
+					scrollSuccess = true
+					scrolledElement = currentElement
+					scrollDelta = actualScrollDelta
+					break
+				}
+			}
+
+			if (currentElement === document.body || currentElement === document.documentElement) {
+				break
+			}
+			currentElement = currentElement.parentElement
+			attempts++
+		}
+
+		if (scrollSuccess) {
+			return `Scrolled container (${scrolledElement?.tagName}) horizontally by ${scrollDelta}px`
+		} else {
+			return `No horizontally scrollable container found for element (${targetElement.tagName})`
+		}
+	}
+
+	// Page-level scrolling (default or fallback)
+
+	const dx = scroll_amount
+
+	const bigEnough = (el: HTMLElement) => el.clientWidth >= window.innerWidth * 0.5
+	const canScroll = (el: HTMLElement | null): boolean =>
+		Boolean(
+			el &&
+			/(auto|scroll|overlay)/.test(getComputedStyle(el).overflowX) &&
+			el.scrollWidth > el.clientWidth &&
+			bigEnough(el)
+		)
+
+	// @deprecated Same heuristic container search as scrollVertically.
+	// TODO: Remove once LLMs reliably use indexed scrolling via data-scrollable.
+
+	let el: HTMLElement | null = document.activeElement as HTMLElement | null
+	while (el && !canScroll(el) && el !== document.body) el = el.parentElement
+
+	el = canScroll(el)
+		? el
+		: Array.from(document.querySelectorAll<HTMLElement>('*')).find(canScroll) ||
+			(document.scrollingElement as HTMLElement) ||
+			(document.documentElement as HTMLElement)
+
+	if (el === document.scrollingElement || el === document.documentElement || el === document.body) {
+		// Page-level scroll
+		const scrollBefore = window.scrollX
+		const scrollMax = document.documentElement.scrollWidth - window.innerWidth
+
+		window.scrollBy(dx, 0)
+
+		const scrollAfter = window.scrollX
+		const scrolled = scrollAfter - scrollBefore
+
+		if (Math.abs(scrolled) < 1) {
+			return dx > 0
+				? `⚠️ Already at the right edge of the page, cannot scroll right further.`
+				: `⚠️ Already at the left edge of the page, cannot scroll left further.`
+		}
+
+		const reachedRight = dx > 0 && scrollAfter >= scrollMax - 1
+		const reachedLeft = dx < 0 && scrollAfter <= 1
+
+		if (reachedRight)
+			return `✅ Scrolled page by ${scrolled}px. Reached the right edge of the page.`
+		if (reachedLeft) return `✅ Scrolled page by ${scrolled}px. Reached the left edge of the page.`
+		return `✅ Scrolled page horizontally by ${scrolled}px.`
+	} else {
+		// Container scroll
+		const warningMsg = `The document is not scrollable. Falling back to container scroll.`
+		console.log(`[PageController] ${warningMsg}`)
+
+		const scrollBefore = el!.scrollLeft
+		const scrollMax = el!.scrollWidth - el!.clientWidth
+
+		el!.scrollBy({ left: dx, behavior: 'smooth' })
+		await waitFor(0.1)
+
+		const scrollAfter = el!.scrollLeft
+		const scrolled = scrollAfter - scrollBefore
+
+		if (Math.abs(scrolled) < 1) {
+			return dx > 0
+				? `⚠️ ${warningMsg} Already at the right edge of container (${el!.tagName}), cannot scroll right further.`
+				: `⚠️ ${warningMsg} Already at the left edge of container (${el!.tagName}), cannot scroll left further.`
+		}
+
+		const reachedRight = dx > 0 && scrollAfter >= scrollMax - 1
+		const reachedLeft = dx < 0 && scrollAfter <= 1
+
+		if (reachedRight)
+			return `✅ ${warningMsg} Scrolled container (${el!.tagName}) by ${scrolled}px. Reached the right edge.`
+		if (reachedLeft)
+			return `✅ ${warningMsg} Scrolled container (${el!.tagName}) by ${scrolled}px. Reached the left edge.`
+		return `✅ ${warningMsg} Scrolled container (${el!.tagName}) horizontally by ${scrolled}px.`
+	}
+}
diff --git a/packages/page-controller/src/dom/dom_tree/index.d.ts b/packages/page-controller/src/dom/dom_tree/index.d.ts
new file mode 100644
index 0000000..4e37d52
--- /dev/null
+++ b/packages/page-controller/src/dom/dom_tree/index.d.ts
@@ -0,0 +1,16 @@
+import type { FlatDomTree } from './type'
+
+interface DomTreeArgs {
+	doHighlightElements?: boolean
+	focusHighlightIndex?: number
+	viewportExpansion?: number
+	debugMode?: boolean
+	interactiveBlacklist?: Element[]
+	interactiveWhitelist?: Element[]
+	highlightOpacity?: number
+	highlightLabelOpacity?: number
+}
+
+declare const domTree: (args?: DomTreeArgs) => FlatDomTree
+
+export default domTree
diff --git a/packages/page-controller/src/dom/dom_tree/index.js b/packages/page-controller/src/dom/dom_tree/index.js
new file mode 100644
index 0000000..7f6b3af
--- /dev/null
+++ b/packages/page-controller/src/dom/dom_tree/index.js
@@ -0,0 +1,1745 @@
+/**
+ * @file port from browser-use
+ * @see https://github.com/browser-use/browser-use/commits/main/browser_use/dom/dom_tree/index.js
+ * @match 0.5.9 d51b6e73daff7165fdd3e44debd667e7f5f7fdc5
+ *
+ * search @edit for all the changed lines.
+ *
+ * @edit export
+ * @edit add interactiveBlacklist interactiveWhitelist
+ * @edit adjustable opacity
+ * @edit direct dom ref
+ * @edit @workaround input.checked
+ * @edit smaller zIndex for highlight
+ * @edit no need for xpath
+ * @edit add `extra` field for extra data
+ * @edit scrollable element detection
+ * @edit add `data-browser-use-ignore` attribute
+ * @edit improve `sampleRect`, filter out rects with 0 area
+ * @edit exclude aria-hidden elements
+ * @edit make sure attributes exist for interactive candidates.
+ * @edit fix "aria-*" attributes check
+ */
+
+export default (
+	args = {
+		doHighlightElements: true,
+		focusHighlightIndex: -1,
+		viewportExpansion: 0,
+		debugMode: false,
+
+		/**
+		 * @edit
+		 */
+		/** @type {Element[]} */
+		interactiveBlacklist: [],
+		/** @type {Element[]} */
+		interactiveWhitelist: [],
+		highlightOpacity: 0.1,
+		highlightLabelOpacity: 0.5,
+	}
+) => {
+	/**
+	 * @edit
+	 */
+	const { interactiveBlacklist, interactiveWhitelist, highlightOpacity, highlightLabelOpacity } =
+		args
+
+	const { doHighlightElements, focusHighlightIndex, viewportExpansion, debugMode } = args
+	let highlightIndex = 0 // Reset highlight index
+
+	/**
+	 * @edit add `extra` field for extra data
+	 */
+	const extraData = new WeakMap()
+	function addExtraData(element, data) {
+		if (!element || element.nodeType !== Node.ELEMENT_NODE) return
+		extraData.set(element, { ...extraData.get(element), ...data })
+	}
+
+	// Add caching mechanisms at the top level
+	const DOM_CACHE = {
+		boundingRects: new WeakMap(),
+		clientRects: new WeakMap(),
+		computedStyles: new WeakMap(),
+		clearCache: () => {
+			DOM_CACHE.boundingRects = new WeakMap()
+			DOM_CACHE.clientRects = new WeakMap()
+			DOM_CACHE.computedStyles = new WeakMap()
+		},
+	}
+
+	/**
+	 * Gets the cached bounding rect for an element.
+	 *
+	 * @param {HTMLElement} element - The element to get the bounding rect for.
+	 * @returns {DOMRect | null} The cached bounding rect, or null if the element is not found.
+	 */
+	function getCachedBoundingRect(element) {
+		if (!element) return null
+
+		if (DOM_CACHE.boundingRects.has(element)) {
+			return DOM_CACHE.boundingRects.get(element)
+		}
+
+		const rect = element.getBoundingClientRect()
+
+		if (rect) {
+			DOM_CACHE.boundingRects.set(element, rect)
+		}
+		return rect
+	}
+
+	/**
+	 * Gets the cached computed style for an element.
+	 *
+	 * @param {HTMLElement} element - The element to get the computed style for.
+	 * @returns {CSSStyleDeclaration | null} The cached computed style, or null if the element is not found.
+	 */
+	function getCachedComputedStyle(element) {
+		if (!element) return null
+
+		if (DOM_CACHE.computedStyles.has(element)) {
+			return DOM_CACHE.computedStyles.get(element)
+		}
+
+		const style = window.getComputedStyle(element)
+
+		if (style) {
+			DOM_CACHE.computedStyles.set(element, style)
+		}
+		return style
+	}
+
+	/**
+	 * Gets the cached client rects for an element.
+	 *
+	 * @param {HTMLElement} element - The element to get the client rects for.
+	 * @returns {DOMRectList | null} The cached client rects, or null if the element is not found.
+	 */
+	function getCachedClientRects(element) {
+		if (!element) return null
+
+		if (DOM_CACHE.clientRects.has(element)) {
+			return DOM_CACHE.clientRects.get(element)
+		}
+
+		const rects = element.getClientRects()
+
+		if (rects) {
+			DOM_CACHE.clientRects.set(element, rects)
+		}
+		return rects
+	}
+
+	/**
+	 * Hash map of DOM nodes indexed by their highlight index.
+	 *
+	 * @type {Object<string, any>}
+	 */
+	const DOM_HASH_MAP = {}
+
+	const ID = { current: 0 }
+
+	const HIGHLIGHT_CONTAINER_ID = 'playwright-highlight-container'
+
+	// Add a WeakMap cache for XPath strings
+	const xpathCache = new WeakMap()
+
+	// // Initialize once and reuse
+	// const viewportObserver = new IntersectionObserver(
+	//   (entries) => {
+	//     entries.forEach(entry => {
+	//       elementVisibilityMap.set(entry.target, entry.isIntersecting);
+	//     });
+	//   },
+	//   { rootMargin: `${viewportExpansion}px` }
+	// );
+
+	/**
+	 * Highlights an element in the DOM and returns the index of the next element.
+	 *
+	 * @param {HTMLElement} element - The element to highlight.
+	 * @param {number} index - The index of the element.
+	 * @param {HTMLElement | null} parentIframe - The parent iframe node.
+	 * @returns {number} The index of the next element.
+	 */
+	function highlightElement(element, index, parentIframe = null) {
+		if (!element) return index
+
+		const overlays = []
+		/**
+		 * @type {HTMLElement | null}
+		 */
+		let label = null
+		let labelWidth = 20
+		let labelHeight = 16
+		let cleanupFn = null
+
+		try {
+			// Create or get highlight container
+			let container = document.getElementById(HIGHLIGHT_CONTAINER_ID)
+			if (!container) {
+				container = document.createElement('div')
+				container.id = HIGHLIGHT_CONTAINER_ID
+				container.style.position = 'fixed'
+				container.style.pointerEvents = 'none'
+				container.style.top = '0'
+				container.style.left = '0'
+				container.style.width = '100%'
+				container.style.height = '100%'
+
+				/**
+				 * @edit smaller zIndex for highlight
+				 */
+				// Use the maximum valid value in zIndex to ensure the element is not blocked by overlapping elements.
+				// container.style.zIndex = "2147483647";
+				container.style.zIndex = '2147483640'
+
+				container.style.backgroundColor = 'transparent'
+				document.body.appendChild(container)
+			}
+
+			// Get element client rects
+			const rects = element.getClientRects() // Use getClientRects()
+
+			if (!rects || rects.length === 0) return index // Exit if no rects
+
+			// Generate a color based on the index
+			const colors = [
+				'#FF0000',
+				'#00FF00',
+				'#0000FF',
+				'#FFA500',
+				'#800080',
+				'#008080',
+				'#FF69B4',
+				'#4B0082',
+				'#FF4500',
+				'#2E8B57',
+				'#DC143C',
+				'#4682B4',
+			]
+			const colorIndex = index % colors.length
+			let baseColor = colors[colorIndex]
+
+			/**
+			 * @edit adjustable opacity
+			 */
+			// const backgroundColor = baseColor + "1A"; // 10% opacity version of the color
+			const backgroundColor =
+				baseColor +
+				Math.floor(highlightOpacity * 255)
+					.toString(16)
+					.padStart(2, '0')
+			baseColor =
+				baseColor +
+				Math.floor(highlightLabelOpacity * 255)
+					.toString(16)
+					.padStart(2, '0')
+
+			// Get iframe offset if necessary
+			let iframeOffset = { x: 0, y: 0 }
+			if (parentIframe) {
+				const iframeRect = parentIframe.getBoundingClientRect() // Keep getBoundingClientRect for iframe offset
+				iframeOffset.x = iframeRect.left
+				iframeOffset.y = iframeRect.top
+			}
+
+			// Create fragment to hold overlay elements
+			const fragment = document.createDocumentFragment()
+
+			// Create highlight overlays for each client rect
+			for (const rect of rects) {
+				if (rect.width === 0 || rect.height === 0) continue // Skip empty rects
+
+				const overlay = document.createElement('div')
+				overlay.style.position = 'fixed'
+				overlay.style.border = `2px solid ${baseColor}`
+				overlay.style.backgroundColor = backgroundColor
+				overlay.style.pointerEvents = 'none'
+				overlay.style.boxSizing = 'border-box'
+
+				const top = rect.top + iframeOffset.y
+				const left = rect.left + iframeOffset.x
+
+				overlay.style.top = `${top}px`
+				overlay.style.left = `${left}px`
+				overlay.style.width = `${rect.width}px`
+				overlay.style.height = `${rect.height}px`
+
+				fragment.appendChild(overlay)
+				overlays.push({ element: overlay, initialRect: rect }) // Store overlay and its rect
+			}
+
+			// Create and position a single label relative to the first rect
+			const firstRect = rects[0]
+			label = document.createElement('div')
+			label.className = 'playwright-highlight-label'
+			label.style.position = 'fixed'
+			label.style.background = baseColor
+			label.style.color = 'white'
+			label.style.padding = '1px 4px'
+			label.style.borderRadius = '4px'
+			label.style.fontSize = `${Math.min(12, Math.max(8, firstRect.height / 2))}px`
+			label.textContent = index.toString()
+
+			labelWidth = label.offsetWidth > 0 ? label.offsetWidth : labelWidth // Update actual width if possible
+			labelHeight = label.offsetHeight > 0 ? label.offsetHeight : labelHeight // Update actual height if possible
+
+			const firstRectTop = firstRect.top + iframeOffset.y
+			const firstRectLeft = firstRect.left + iframeOffset.x
+
+			let labelTop = firstRectTop + 2
+			let labelLeft = firstRectLeft + firstRect.width - labelWidth - 2
+
+			// Adjust label position if first rect is too small
+			if (firstRect.width < labelWidth + 4 || firstRect.height < labelHeight + 4) {
+				labelTop = firstRectTop - labelHeight - 2
+				labelLeft = firstRectLeft + firstRect.width - labelWidth // Align with right edge
+				if (labelLeft < iframeOffset.x) labelLeft = firstRectLeft // Prevent going off-left
+			}
+
+			// Ensure label stays within viewport bounds slightly better
+			labelTop = Math.max(0, Math.min(labelTop, window.innerHeight - labelHeight))
+			labelLeft = Math.max(0, Math.min(labelLeft, window.innerWidth - labelWidth))
+
+			label.style.top = `${labelTop}px`
+			label.style.left = `${labelLeft}px`
+
+			fragment.appendChild(label)
+
+			// Update positions on scroll/resize
+			const updatePositions = () => {
+				const newRects = element.getClientRects() // Get fresh rects
+				let newIframeOffset = { x: 0, y: 0 }
+
+				if (parentIframe) {
+					const iframeRect = parentIframe.getBoundingClientRect() // Keep getBoundingClientRect for iframe
+					newIframeOffset.x = iframeRect.left
+					newIframeOffset.y = iframeRect.top
+				}
+
+				// Update each overlay
+				overlays.forEach((overlayData, i) => {
+					if (i < newRects.length) {
+						// Check if rect still exists
+						const newRect = newRects[i]
+						const newTop = newRect.top + newIframeOffset.y
+						const newLeft = newRect.left + newIframeOffset.x
+
+						overlayData.element.style.top = `${newTop}px`
+						overlayData.element.style.left = `${newLeft}px`
+						overlayData.element.style.width = `${newRect.width}px`
+						overlayData.element.style.height = `${newRect.height}px`
+						overlayData.element.style.display =
+							newRect.width === 0 || newRect.height === 0 ? 'none' : 'block'
+					} else {
+						// If fewer rects now, hide extra overlays
+						overlayData.element.style.display = 'none'
+					}
+				})
+
+				// If there are fewer new rects than overlays, hide the extras
+				if (newRects.length < overlays.length) {
+					for (let i = newRects.length; i < overlays.length; i++) {
+						overlays[i].element.style.display = 'none'
+					}
+				}
+
+				// Update label position based on the first new rect
+				if (label && newRects.length > 0) {
+					const firstNewRect = newRects[0]
+					const firstNewRectTop = firstNewRect.top + newIframeOffset.y
+					const firstNewRectLeft = firstNewRect.left + newIframeOffset.x
+
+					let newLabelTop = firstNewRectTop + 2
+					let newLabelLeft = firstNewRectLeft + firstNewRect.width - labelWidth - 2
+
+					if (firstNewRect.width < labelWidth + 4 || firstNewRect.height < labelHeight + 4) {
+						newLabelTop = firstNewRectTop - labelHeight - 2
+						newLabelLeft = firstNewRectLeft + firstNewRect.width - labelWidth
+						if (newLabelLeft < newIframeOffset.x) newLabelLeft = firstNewRectLeft
+					}
+
+					// Ensure label stays within viewport bounds
+					newLabelTop = Math.max(0, Math.min(newLabelTop, window.innerHeight - labelHeight))
+					newLabelLeft = Math.max(0, Math.min(newLabelLeft, window.innerWidth - labelWidth))
+
+					label.style.top = `${newLabelTop}px`
+					label.style.left = `${newLabelLeft}px`
+					label.style.display = 'block'
+				} else if (label) {
+					// Hide label if element has no rects anymore
+					label.style.display = 'none'
+				}
+			}
+
+			const throttleFunction = (func, delay) => {
+				let lastCall = 0
+				return (...args) => {
+					const now = performance.now()
+					if (now - lastCall < delay) return
+					lastCall = now
+					return func(...args)
+				}
+			}
+
+			const throttledUpdatePositions = throttleFunction(updatePositions, 16) // ~60fps
+			window.addEventListener('scroll', throttledUpdatePositions, true)
+			window.addEventListener('resize', throttledUpdatePositions)
+
+			// Add cleanup function
+			cleanupFn = () => {
+				window.removeEventListener('scroll', throttledUpdatePositions, true)
+				window.removeEventListener('resize', throttledUpdatePositions)
+				// Remove overlay elements if needed
+				overlays.forEach((overlay) => overlay.element.remove())
+				if (label) label.remove()
+			}
+
+			// Then add fragment to container in one operation
+			container.appendChild(fragment)
+
+			return index + 1
+		} finally {
+			// Store cleanup function for later use
+			if (cleanupFn) {
+				// Keep a reference to cleanup functions in a global array
+				;(window._highlightCleanupFunctions = window._highlightCleanupFunctions || []).push(
+					cleanupFn
+				)
+			}
+		}
+	}
+
+	// // Add this function to perform cleanup when needed
+	// function cleanupHighlights() {
+	//   if (window._highlightCleanupFunctions && window._highlightCleanupFunctions.length) {
+	//     window._highlightCleanupFunctions.forEach(fn => fn());
+	//     window._highlightCleanupFunctions = [];
+	//   }
+
+	//   // Also remove the container
+	//   const container = document.getElementById(HIGHLIGHT_CONTAINER_ID);
+	//   if (container) container.remove();
+	// }
+
+	/**
+	 * Gets the position of an element in its parent.
+	 *
+	 * @param {HTMLElement} currentElement - The element to get the position for.
+	 * @returns {number} The position of the element in its parent.
+	 */
+	function getElementPosition(currentElement) {
+		if (!currentElement.parentElement) {
+			return 0 // No parent means no siblings
+		}
+
+		const tagName = currentElement.nodeName.toLowerCase()
+
+		const siblings = Array.from(currentElement.parentElement.children).filter(
+			(sib) => sib.nodeName.toLowerCase() === tagName
+		)
+
+		if (siblings.length === 1) {
+			return 0 // Only element of its type
+		}
+
+		const index = siblings.indexOf(currentElement) + 1 // 1-based index
+		return index
+	}
+
+	function getXPathTree(element, stopAtBoundary = true) {
+		if (xpathCache.has(element)) return xpathCache.get(element)
+
+		const segments = []
+		let currentElement = element
+
+		while (currentElement && currentElement.nodeType === Node.ELEMENT_NODE) {
+			// Stop if we hit a shadow root or iframe
+			if (
+				stopAtBoundary &&
+				(currentElement.parentNode instanceof ShadowRoot ||
+					currentElement.parentNode instanceof HTMLIFrameElement)
+			) {
+				break
+			}
+
+			const position = getElementPosition(currentElement)
+			const tagName = currentElement.nodeName.toLowerCase()
+			const xpathIndex = position > 0 ? `[${position}]` : ''
+			segments.unshift(`${tagName}${xpathIndex}`)
+
+			currentElement = currentElement.parentNode
+		}
+
+		const result = segments.join('/')
+		xpathCache.set(element, result)
+		return result
+	}
+
+	/**
+	 * @edit scrollable element detection
+	 * Checks if an element is scrollable. if so, return the scrollable distance on each direction (left right top bottom). if not return null.
+	 * @note distance smaller than 4 will be considered as not scrollable.
+	 * @note only check block elements, not inline elements.
+	 */
+	function isScrollableElement(element) {
+		if (!element || element.nodeType !== Node.ELEMENT_NODE) {
+			return null // Not a valid element
+		}
+
+		const style = getCachedComputedStyle(element)
+		if (!style) return null
+
+		// Check if the element is a block-level element
+		const display = style.display
+		if (display === 'inline' || display === 'inline-block') {
+			return null // Not a block-level element
+		}
+
+		// Check overflow properties
+		const overflowX = style.overflowX
+		const overflowY = style.overflowY
+
+		// scrollbar-width/scrollbar-gutter are only set on elements designed to scroll;
+		// their presence signals scroll intent even when overflow is hidden (e.g. overflow: auto on :hover)
+		const hasScrollbarSignal =
+			(style.scrollbarWidth && style.scrollbarWidth !== 'auto') ||
+			(style.scrollbarGutter && style.scrollbarGutter !== 'auto')
+
+		const scrollableX = overflowX === 'auto' || overflowX === 'scroll'
+		const scrollableY = overflowY === 'auto' || overflowY === 'scroll'
+
+		if (!scrollableX && !scrollableY && !hasScrollbarSignal) {
+			return null // Not scrollable in any direction
+		}
+
+		const scrollWidth = element.scrollWidth - element.clientWidth
+		const scrollHeight = element.scrollHeight - element.clientHeight
+
+		// Consider small distances as not scrollable
+		const threshold = 4
+
+		if (scrollWidth < threshold && scrollHeight < threshold) {
+			return null // Not scrollable
+		}
+
+		if (!scrollableY && !hasScrollbarSignal && scrollWidth < threshold) {
+			return null // Not scrollable horizontally
+		}
+
+		if (!scrollableX && !hasScrollbarSignal && scrollHeight < threshold) {
+			return null // Not scrollable vertically
+		}
+
+		const distanceToTop = element.scrollTop
+		const distanceToLeft = element.scrollLeft
+		const distanceToRight = element.scrollWidth - element.clientWidth - element.scrollLeft
+		const distanceToBottom = element.scrollHeight - element.clientHeight - element.scrollTop
+
+		const scrollData = {
+			top: distanceToTop,
+			right: distanceToRight,
+			bottom: distanceToBottom,
+			left: distanceToLeft,
+		}
+
+		// Store extra data for the element
+		addExtraData(element, {
+			scrollable: true,
+			scrollData: scrollData,
+		})
+
+		return scrollData
+	}
+
+	/**
+	 * Checks if a text node is visible.
+	 *
+	 * @param {Text} textNode - The text node to check.
+	 * @returns {boolean} Whether the text node is visible.
+	 */
+	function isTextNodeVisible(textNode) {
+		try {
+			// Special case: when viewportExpansion is -1, consider all text nodes as visible
+			if (viewportExpansion === -1) {
+				// Still check parent visibility for basic filtering
+				const parentElement = textNode.parentElement
+				if (!parentElement) return false
+
+				try {
+					return parentElement.checkVisibility({
+						checkOpacity: true,
+						checkVisibilityCSS: true,
+					})
+				} catch (e) {
+					// Fallback if checkVisibility is not supported
+					const style = window.getComputedStyle(parentElement)
+					return style.display !== 'none' && style.visibility !== 'hidden' && style.opacity !== '0'
+				}
+			}
+
+			const range = document.createRange()
+			range.selectNodeContents(textNode)
+			const rects = range.getClientRects() // Use getClientRects for Range
+
+			if (!rects || rects.length === 0) {
+				return false
+			}
+
+			let isAnyRectVisible = false
+			let isAnyRectInViewport = false
+
+			for (const rect of rects) {
+				// Check size
+				if (rect.width > 0 && rect.height > 0) {
+					isAnyRectVisible = true
+
+					// Viewport check for this rect
+					if (!(
+						rect.bottom < -viewportExpansion ||
+						rect.top > window.innerHeight + viewportExpansion ||
+						rect.right < -viewportExpansion ||
+						rect.left > window.innerWidth + viewportExpansion
+					)) {
+						isAnyRectInViewport = true
+						break // Found a visible rect in viewport, no need to check others
+					}
+				}
+			}
+
+			if (!isAnyRectVisible || !isAnyRectInViewport) {
+				return false
+			}
+
+			// Check parent visibility
+			const parentElement = textNode.parentElement
+			if (!parentElement) return false
+
+			try {
+				return parentElement.checkVisibility({
+					checkOpacity: true,
+					checkVisibilityCSS: true,
+				})
+			} catch (e) {
+				// Fallback if checkVisibility is not supported
+				const style = window.getComputedStyle(parentElement)
+				return style.display !== 'none' && style.visibility !== 'hidden' && style.opacity !== '0'
+			}
+		} catch (e) {
+			console.warn('Error checking text node visibility:', e)
+			return false
+		}
+	}
+
+	/**
+	 * Checks if an element is accepted.
+	 *
+	 * @param {HTMLElement} element - The element to check.
+	 * @returns {boolean} Whether the element is accepted.
+	 */
+	function isElementAccepted(element) {
+		if (!element || !element.tagName) return false
+
+		// Always accept body and common container elements
+		const alwaysAccept = new Set([
+			'body',
+			'div',
+			'main',
+			'article',
+			'section',
+			'nav',
+			'header',
+			'footer',
+		])
+		const tagName = element.tagName.toLowerCase()
+
+		if (alwaysAccept.has(tagName)) return true
+
+		const leafElementDenyList = new Set([
+			'svg',
+			'script',
+			'style',
+			'link',
+			'meta',
+			'noscript',
+			'template',
+		])
+
+		return !leafElementDenyList.has(tagName)
+	}
+
+	/**
+	 * Checks if an element is visible.
+	 *
+	 * @param {HTMLElement} element - The element to check.
+	 * @returns {boolean} Whether the element is visible.
+	 */
+	function isElementVisible(element) {
+		const style = getCachedComputedStyle(element)
+		return (
+			element.offsetWidth > 0 &&
+			element.offsetHeight > 0 &&
+			style?.visibility !== 'hidden' &&
+			style?.display !== 'none'
+		)
+	}
+
+	/**
+	 * Checks if an element is interactive.
+	 *
+	 * lots of comments, and uncommented code - to show the logic of what we already tried
+	 *
+	 * One of the things we tried at the beginning was also to use event listeners, and other fancy class, style stuff -> what actually worked best was just combining most things with computed cursor style :)
+	 *
+	 * @param {HTMLElement} element - The element to check.
+	 */
+	function isInteractiveElement(element) {
+		if (!element || element.nodeType !== Node.ELEMENT_NODE) {
+			return false
+		}
+
+		/**
+		 * @edit add interactiveBlacklist interactiveWhitelist
+		 */
+		if (interactiveBlacklist.includes(element)) {
+			return false // Skip blacklisted elements
+		}
+		if (interactiveWhitelist.includes(element)) {
+			return true // Skip whitelisted elements
+		}
+
+		// Cache the tagName and style lookups
+		const tagName = element.tagName.toLowerCase()
+		const style = getCachedComputedStyle(element)
+
+		// Define interactive cursors
+		const interactiveCursors = new Set([
+			'pointer', // Link/clickable elements
+			'move', // Movable elements
+			'text', // Text selection
+			'grab', // Grabbable elements
+			'grabbing', // Currently grabbing
+			'cell', // Table cell selection
+			'copy', // Copy operation
+			'alias', // Alias creation
+			'all-scroll', // Scrollable content
+			'col-resize', // Column resize
+			'context-menu', // Context menu available
+			'crosshair', // Precise selection
+			'e-resize', // East resize
+			'ew-resize', // East-west resize
+			'help', // Help available
+			'n-resize', // North resize
+			'ne-resize', // Northeast resize
+			'nesw-resize', // Northeast-southwest resize
+			'ns-resize', // North-south resize
+			'nw-resize', // Northwest resize
+			'nwse-resize', // Northwest-southeast resize
+			'row-resize', // Row resize
+			's-resize', // South resize
+			'se-resize', // Southeast resize
+			'sw-resize', // Southwest resize
+			'vertical-text', // Vertical text selection
+			'w-resize', // West resize
+			'zoom-in', // Zoom in
+			'zoom-out', // Zoom out
+		])
+
+		// Define non-interactive cursors
+		const nonInteractiveCursors = new Set([
+			'not-allowed', // Action not allowed
+			'no-drop', // Drop not allowed
+			'wait', // Processing
+			'progress', // In progress
+			'initial', // Initial value
+			'inherit', // Inherited value
+			//? Let's just include all potentially clickable elements that are not specifically blocked
+			// 'none',        // No cursor
+			// 'default',     // Default cursor
+			// 'auto',        // Browser default
+		])
+
+		/**
+		 * Checks if an element has an interactive pointer.
+		 *
+		 * @param {HTMLElement} element - The element to check.
+		 * @returns {boolean} Whether the element has an interactive pointer.
+		 */
+		function doesElementHaveInteractivePointer(element) {
+			if (element.tagName.toLowerCase() === 'html') return false
+
+			if (style?.cursor && interactiveCursors.has(style.cursor)) return true
+
+			return false
+		}
+
+		let isInteractiveCursor = doesElementHaveInteractivePointer(element)
+
+		// Genius fix for almost all interactive elements
+		if (isInteractiveCursor) {
+			return true
+		}
+
+		const interactiveElements = new Set([
+			'a', // Links
+			'button', // Buttons
+			'input', // All input types (text, checkbox, radio, etc.)
+			'select', // Dropdown menus
+			'textarea', // Text areas
+			'details', // Expandable details
+			'summary', // Summary element (clickable part of details)
+			'label', // Form labels (often clickable)
+			'option', // Select options
+			'optgroup', // Option groups
+			'fieldset', // Form fieldsets (can be interactive with legend)
+			'legend', // Fieldset legends
+		])
+
+		// Define explicit disable attributes and properties
+		const explicitDisableTags = new Set([
+			'disabled', // Standard disabled attribute
+			// 'aria-disabled',      // ARIA disabled state
+			'readonly', // Read-only state
+			// 'aria-readonly',     // ARIA read-only state
+			// 'aria-hidden',       // Hidden from accessibility
+			// 'hidden',            // Hidden attribute
+			// 'inert',             // Inert attribute
+			// 'aria-inert',        // ARIA inert state
+			// 'tabindex="-1"',     // Removed from tab order
+			// 'aria-hidden="true"' // Hidden from screen readers
+		])
+
+		// handle inputs, select, checkbox, radio, textarea, button and make sure they are not cursor style disabled/not-allowed
+		if (interactiveElements.has(tagName)) {
+			// Check for non-interactive cursor
+			if (style?.cursor && nonInteractiveCursors.has(style.cursor)) {
+				return false
+			}
+
+			// Check for explicit disable attributes
+			for (const disableTag of explicitDisableTags) {
+				if (
+					element.hasAttribute(disableTag) ||
+					element.getAttribute(disableTag) === 'true' ||
+					element.getAttribute(disableTag) === ''
+				) {
+					return false
+				}
+			}
+
+			// Check for disabled property on form elements
+			if (element.disabled) {
+				return false
+			}
+
+			// Check for readonly property on form elements
+			if (element.readOnly) {
+				return false
+			}
+
+			// Check for inert property
+			if (element.inert) {
+				return false
+			}
+
+			return true
+		}
+
+		const role = element.getAttribute('role')
+		const ariaRole = element.getAttribute('aria-role')
+
+		// Check for contenteditable attribute
+		if (element.getAttribute('contenteditable') === 'true' || element.isContentEditable) {
+			return true
+		}
+
+		// Added enhancement to capture dropdown interactive elements
+		if (
+			element.classList &&
+			(element.classList.contains('button') ||
+				element.classList.contains('dropdown-toggle') ||
+				element.getAttribute('data-index') ||
+				element.getAttribute('data-toggle') === 'dropdown' ||
+				element.getAttribute('aria-haspopup') === 'true')
+		) {
+			return true
+		}
+
+		const interactiveRoles = new Set([
+			'button', // Directly clickable element
+			// 'link',            // Clickable link
+			'menu', // Menu container (ARIA menus)
+			'menubar', // Menu bar container
+			'menuitem', // Clickable menu item
+			'menuitemradio', // Radio-style menu item (selectable)
+			'menuitemcheckbox', // Checkbox-style menu item (toggleable)
+			'radio', // Radio button (selectable)
+			'checkbox', // Checkbox (toggleable)
+			'tab', // Tab (clickable to switch content)
+			'switch', // Toggle switch (clickable to change state)
+			'slider', // Slider control (draggable)
+			'spinbutton', // Number input with up/down controls
+			'combobox', // Dropdown with text input
+			'searchbox', // Search input field
+			'textbox', // Text input field
+			'listbox', // Selectable list
+			'option', // Selectable option in a list
+			'scrollbar', // Scrollable control
+		])
+
+		// Basic role/attribute checks
+		const hasInteractiveRole =
+			interactiveElements.has(tagName) ||
+			(role && interactiveRoles.has(role)) ||
+			(ariaRole && interactiveRoles.has(ariaRole))
+
+		if (hasInteractiveRole) return true
+
+		// check whether element has event listeners by window.getEventListeners
+		try {
+			if (typeof getEventListeners === 'function') {
+				const listeners = getEventListeners(element)
+				const mouseEvents = ['click', 'mousedown', 'mouseup', 'dblclick']
+				for (const eventType of mouseEvents) {
+					if (listeners[eventType] && listeners[eventType].length > 0) {
+						return true // Found a mouse interaction listener
+					}
+				}
+			}
+
+			const getEventListenersForNode =
+				element?.ownerDocument?.defaultView?.getEventListenersForNode ||
+				window.getEventListenersForNode
+			if (typeof getEventListenersForNode === 'function') {
+				const listeners = getEventListenersForNode(element)
+				const interactionEvents = [
+					'click',
+					'mousedown',
+					'mouseup',
+					'keydown',
+					'keyup',
+					'submit',
+					'change',
+					'input',
+					'focus',
+					'blur',
+				]
+				for (const eventType of interactionEvents) {
+					for (const listener of listeners) {
+						if (listener.type === eventType) {
+							return true // Found a common interaction listener
+						}
+					}
+				}
+			}
+			// Fallback: Check common event attributes if getEventListeners is not available (getEventListeners doesn't work in page.evaluate context)
+			const commonMouseAttrs = ['onclick', 'onmousedown', 'onmouseup', 'ondblclick']
+			for (const attr of commonMouseAttrs) {
+				if (element.hasAttribute(attr) || typeof element[attr] === 'function') {
+					return true
+				}
+			}
+		} catch (e) {
+			// console.warn(`Could not check event listeners for ${element.tagName}:`, e);
+			// If checking listeners fails, rely on other checks
+		}
+
+		/**
+		 * @edit scrollable element detection
+		 */
+		if (isScrollableElement(element)) {
+			return true
+		}
+
+		return false
+	}
+
+	/**
+	 * Checks if an element is the topmost element at its position.
+	 *
+	 * @param {HTMLElement} element - The element to check.
+	 * @returns {boolean} Whether the element is the topmost element at its position.
+	 */
+	function isTopElement(element) {
+		// Special case: when viewportExpansion is -1, consider all elements as "top" elements
+		if (viewportExpansion === -1) {
+			return true
+		}
+
+		const rects = getCachedClientRects(element) // Replace element.getClientRects()
+
+		if (!rects || rects.length === 0) {
+			return false // No geometry, cannot be top
+		}
+
+		let isAnyRectInViewport = false
+		for (const rect of rects) {
+			// Use the same logic as isInExpandedViewport check
+			if (
+				rect.width > 0 &&
+				rect.height > 0 &&
+				!(
+					// Only check non-empty rects
+					rect.bottom < -viewportExpansion ||
+					rect.top > window.innerHeight + viewportExpansion ||
+					rect.right < -viewportExpansion ||
+					rect.left > window.innerWidth + viewportExpansion
+				)
+			) {
+				isAnyRectInViewport = true
+				break
+			}
+		}
+
+		if (!isAnyRectInViewport) {
+			return false // All rects are outside the viewport area
+		}
+
+		// Find the correct document context and root element
+		let doc = element.ownerDocument
+
+		// If we're in an iframe, elements are considered top by default
+		if (doc !== window.document) {
+			return true
+		}
+
+		/**
+		 * @edit improve `sampleRect`, filter out rects with 0 area
+		 */
+		// find a rect that has width and height as sample
+		let rect = Array.from(rects).find((r) => r.width > 0 && r.height > 0)
+		if (!rect) {
+			return false // No valid rect found
+		}
+
+		// For shadow DOM, we need to check within its own root context
+		const shadowRoot = element.getRootNode()
+		if (shadowRoot instanceof ShadowRoot) {
+			const centerX = rect.left + rect.width / 2
+			const centerY = rect.top + rect.height / 2
+
+			try {
+				const topEl = shadowRoot.elementFromPoint(centerX, centerY)
+				if (!topEl) return false
+
+				let current = topEl
+				while (current && current !== shadowRoot) {
+					if (current === element) return true
+					current = current.parentElement
+				}
+				return false
+			} catch (e) {
+				return true
+			}
+		}
+
+		const margin = 5
+
+		// For elements in viewport, check if they're topmost. Do the check in the
+		// center of the element and at the corners to ensure we catch more cases.
+		const checkPoints = [
+			// Initially only this was used, but it was not enough
+			{ x: rect.left + rect.width / 2, y: rect.top + rect.height / 2 },
+			{ x: rect.left + margin, y: rect.top + margin }, // top left
+			// { x: rect.right - margin, y: rect.top + margin },    // top right
+			// { x: rect.left + margin, y: rect.bottom - margin },  // bottom left
+			{ x: rect.right - margin, y: rect.bottom - margin }, // bottom right
+		]
+
+		return checkPoints.some(({ x, y }) => {
+			try {
+				const topEl = document.elementFromPoint(x, y)
+				if (!topEl) return false
+
+				let current = topEl
+				while (current && current !== document.documentElement) {
+					if (current === element) return true
+					current = current.parentElement
+				}
+				return false
+			} catch (e) {
+				return true
+			}
+		})
+	}
+
+	/**
+	 * Checks if an element is within the expanded viewport.
+	 *
+	 * @param {HTMLElement} element - The element to check.
+	 * @param {number} viewportExpansion - The viewport expansion.
+	 * @returns {boolean} Whether the element is within the expanded viewport.
+	 */
+	function isInExpandedViewport(element, viewportExpansion) {
+		if (viewportExpansion === -1) {
+			return true
+		}
+
+		const rects = element.getClientRects() // Use getClientRects
+
+		if (!rects || rects.length === 0) {
+			// Fallback to getBoundingClientRect if getClientRects is empty,
+			// useful for elements like <svg> that might not have client rects but have a bounding box.
+			const boundingRect = getCachedBoundingRect(element)
+			if (!boundingRect || boundingRect.width === 0 || boundingRect.height === 0) {
+				return false
+			}
+			return !(
+				boundingRect.bottom < -viewportExpansion ||
+				boundingRect.top > window.innerHeight + viewportExpansion ||
+				boundingRect.right < -viewportExpansion ||
+				boundingRect.left > window.innerWidth + viewportExpansion
+			)
+		}
+
+		// Check if *any* client rect is within the viewport
+		for (const rect of rects) {
+			if (rect.width === 0 || rect.height === 0) continue // Skip empty rects
+
+			if (!(
+				rect.bottom < -viewportExpansion ||
+				rect.top > window.innerHeight + viewportExpansion ||
+				rect.right < -viewportExpansion ||
+				rect.left > window.innerWidth + viewportExpansion
+			)) {
+				return true // Found at least one rect in the viewport
+			}
+		}
+
+		return false // No rects were found in the viewport
+	}
+
+	// /**
+	//  * Gets the effective scroll of an element.
+	//  *
+	//  * @param {HTMLElement} element - The element to get the effective scroll for.
+	//  * @returns {Object} The effective scroll of the element.
+	//  */
+	// function getEffectiveScroll(element) {
+	//   let currentEl = element;
+	//   let scrollX = 0;
+	//   let scrollY = 0;
+
+	//   while (currentEl && currentEl !== document.documentElement) {
+	//     if (currentEl.scrollLeft || currentEl.scrollTop) {
+	//       scrollX += currentEl.scrollLeft;
+	//       scrollY += currentEl.scrollTop;
+	//     }
+	//     currentEl = currentEl.parentElement;
+	//   }
+
+	//   scrollX += window.scrollX;
+	//   scrollY += window.scrollY;
+
+	//   return { scrollX, scrollY };
+	// }
+
+	/**
+	 * Checks if an element is an interactive candidate.
+	 *
+	 * @param {HTMLElement} element - The element to check.
+	 * @returns {boolean} Whether the element is an interactive candidate.
+	 */
+
+	// @edit fix "aria-*" attributes check
+	const INTERACTIVE_ARIA_ATTRS = [
+		'aria-expanded',
+		'aria-checked',
+		'aria-selected',
+		'aria-pressed',
+		'aria-haspopup',
+		'aria-controls',
+		'aria-owns',
+		'aria-activedescendant',
+		'aria-valuenow',
+		'aria-valuetext',
+		'aria-valuemax',
+		'aria-valuemin',
+		'aria-autocomplete',
+	]
+
+	function hasInteractiveAria(el) {
+		for (let i = 0; i < INTERACTIVE_ARIA_ATTRS.length; i++) {
+			if (el.hasAttribute(INTERACTIVE_ARIA_ATTRS[i])) return true
+		}
+		return false
+	}
+
+	function isInteractiveCandidate(element) {
+		if (!element || element.nodeType !== Node.ELEMENT_NODE) return false
+
+		const tagName = element.tagName.toLowerCase()
+
+		// Fast-path for common interactive elements
+		const interactiveElements = new Set([
+			'a',
+			'button',
+			'input',
+			'select',
+			'textarea',
+			'details',
+			'summary',
+			'label',
+		])
+
+		if (interactiveElements.has(tagName)) return true
+
+		// Quick attribute checks without getting full lists
+		const hasQuickInteractiveAttr =
+			element.hasAttribute('onclick') ||
+			element.hasAttribute('role') ||
+			element.hasAttribute('tabindex') ||
+			hasInteractiveAria(element) ||
+			element.hasAttribute('data-action') ||
+			element.getAttribute('contenteditable') === 'true'
+
+		return hasQuickInteractiveAttr
+	}
+
+	// --- Define constants for distinct interaction check ---
+	const DISTINCT_INTERACTIVE_TAGS = new Set([
+		'a',
+		'button',
+		'input',
+		'select',
+		'textarea',
+		'summary',
+		'details',
+		'label',
+		'option',
+		'li',
+	])
+	const DISTINCT_INTERACTIVE_ROLES = new Set([
+		'button',
+		'link',
+		'menuitem',
+		'menuitemradio',
+		'menuitemcheckbox',
+		'radio',
+		'checkbox',
+		'tab',
+		'switch',
+		'slider',
+		'spinbutton',
+		'combobox',
+		'searchbox',
+		'textbox',
+		'listbox',
+		'listitem',
+		'treeitem',
+		'row',
+		'option',
+		'scrollbar',
+	])
+
+	/**
+	 * Heuristically determines if an element should be considered as independently interactive,
+	 * even if it's nested inside another interactive container.
+	 *
+	 * This function helps detect deeply nested actionable elements (e.g., menu items within a button)
+	 * that may not be picked up by strict interactivity checks.
+	 *
+	 * @param {HTMLElement} element - The element to check.
+	 * @returns {boolean} Whether the element is heuristically interactive.
+	 */
+	function isHeuristicallyInteractive(element) {
+		if (!element || element.nodeType !== Node.ELEMENT_NODE) return false
+
+		// Skip non-visible elements early for performance
+		if (!isElementVisible(element)) return false
+
+		// Check for common attributes that often indicate interactivity
+		const hasInteractiveAttributes =
+			element.hasAttribute('role') ||
+			element.hasAttribute('tabindex') ||
+			element.hasAttribute('onclick') ||
+			typeof element.onclick === 'function'
+
+		// Check for semantic class names suggesting interactivity
+		const hasInteractiveClass = /\b(btn|clickable|menu|item|entry|link)\b/i.test(
+			element.className || ''
+		)
+
+		// Determine whether the element is inside a known interactive container
+		const isInKnownContainer = Boolean(
+			element.closest('button,a,[role="button"],.menu,.dropdown,.list,.toolbar')
+		)
+
+		// Ensure the element has at least one visible child (to avoid marking empty wrappers)
+		const hasVisibleChildren = [...element.children].some(isElementVisible)
+
+		// Avoid highlighting elements whose parent is <body> (top-level wrappers)
+		const isParentBody = element.parentElement && element.parentElement.isSameNode(document.body)
+
+		return (
+			(isInteractiveElement(element) || hasInteractiveAttributes || hasInteractiveClass) &&
+			hasVisibleChildren &&
+			isInKnownContainer &&
+			!isParentBody
+		)
+	}
+
+	/**
+	 * Checks if an element likely represents a distinct interaction
+	 * separate from its parent (if the parent is also interactive).
+	 *
+	 * @param {HTMLElement} element - The element to check.
+	 * @returns {boolean} Whether the element is a distinct interaction.
+	 */
+	function isElementDistinctInteraction(element) {
+		if (!element || element.nodeType !== Node.ELEMENT_NODE) {
+			return false
+		}
+
+		const tagName = element.tagName.toLowerCase()
+		const role = element.getAttribute('role')
+
+		// Check if it's an iframe - always distinct boundary
+		if (tagName === 'iframe') {
+			return true
+		}
+
+		// Check tag name
+		if (DISTINCT_INTERACTIVE_TAGS.has(tagName)) {
+			return true
+		}
+		// Check interactive roles
+		if (role && DISTINCT_INTERACTIVE_ROLES.has(role)) {
+			return true
+		}
+		// Check contenteditable
+		if (element.isContentEditable || element.getAttribute('contenteditable') === 'true') {
+			return true
+		}
+		// Check for common testing/automation attributes
+		if (
+			element.hasAttribute('data-testid') ||
+			element.hasAttribute('data-cy') ||
+			element.hasAttribute('data-test')
+		) {
+			return true
+		}
+		// Check for explicit onclick handler (attribute or property)
+		if (element.hasAttribute('onclick') || typeof element.onclick === 'function') {
+			return true
+		}
+		// ARIA state attributes imply the element manages its own interaction state
+		if (hasInteractiveAria(element)) {
+			return true
+		}
+
+		// return false
+
+		// Check for other common interaction event listeners
+		try {
+			const getEventListenersForNode =
+				element?.ownerDocument?.defaultView?.getEventListenersForNode ||
+				window.getEventListenersForNode
+			if (typeof getEventListenersForNode === 'function') {
+				const listeners = getEventListenersForNode(element)
+				const interactionEvents = [
+					'click',
+					'mousedown',
+					'mouseup',
+					'keydown',
+					'keyup',
+					'submit',
+					'change',
+					'input',
+					'focus',
+					'blur',
+				]
+				for (const eventType of interactionEvents) {
+					for (const listener of listeners) {
+						if (listener.type === eventType) {
+							return true // Found a common interaction listener
+						}
+					}
+				}
+			}
+			// Fallback: Check common event attributes if getEventListeners is not available (getEventListenersForNode doesn't work in page.evaluate context)
+			const commonEventAttrs = [
+				'onmousedown',
+				'onmouseup',
+				'onkeydown',
+				'onkeyup',
+				'onsubmit',
+				'onchange',
+				'oninput',
+				'onfocus',
+				'onblur',
+			]
+			if (commonEventAttrs.some((attr) => element.hasAttribute(attr))) {
+				return true
+			}
+		} catch (e) {
+			// console.warn(`Could not check event listeners for ${element.tagName}:`, e);
+			// If checking listeners fails, rely on other checks
+		}
+
+		// if the element is not strictly interactive but appears clickable based on heuristic signals
+		if (isHeuristicallyInteractive(element)) {
+			return true
+		}
+
+		// Scrollable containers are always distinct — the LLM needs their index for targeted scrolling.
+		// Check extraData (already set by isScrollableElement in isInteractiveElement) to avoid redundant layout reads.
+		if (extraData.get(element)?.scrollable) {
+			return true
+		}
+
+		// Default to false: if it's interactive but doesn't match above,
+		// assume it triggers the same action as the parent.
+		return false
+	}
+	// --- End distinct interaction check ---
+
+	/**
+   * Handles the logic for deciding whether to highlight an element and performing the highlight.
+   * @param {
+    {
+        tagName: string;
+        attributes: Record<string, string>;
+        xpath: any;
+        children: never[];
+        isVisible?: boolean;
+        isTopElement?: boolean;
+        isInteractive?: boolean;
+        isInViewport?: boolean;
+        highlightIndex?: number;
+        shadowRoot?: boolean;
+   }} nodeData - The node data object.
+   * @param {HTMLElement} node - The node to highlight.
+   * @param {HTMLElement | null} parentIframe - The parent iframe node.
+   * @param {boolean} isParentHighlighted - Whether the parent node is highlighted.
+   * @returns {boolean} Whether the element was highlighted.
+   */
+	function handleHighlighting(nodeData, node, parentIframe, isParentHighlighted) {
+		if (!nodeData.isInteractive) return false // Not interactive, definitely don't highlight
+
+		let shouldHighlight = false
+		if (!isParentHighlighted) {
+			// Parent wasn't highlighted, this interactive node can be highlighted.
+			shouldHighlight = true
+		} else {
+			// Parent *was* highlighted. Only highlight this node if it represents a distinct interaction.
+			if (isElementDistinctInteraction(node)) {
+				shouldHighlight = true
+			} else {
+				// console.log(`Skipping highlight for ${nodeData.tagName} (parent highlighted)`);
+				shouldHighlight = false
+			}
+		}
+
+		if (shouldHighlight) {
+			// Check viewport status before assigning index and highlighting
+			nodeData.isInViewport = isInExpandedViewport(node, viewportExpansion)
+
+			// When viewportExpansion is -1, all interactive elements should get a highlight index
+			// regardless of viewport status
+			if (nodeData.isInViewport || viewportExpansion === -1) {
+				nodeData.highlightIndex = highlightIndex++
+
+				if (doHighlightElements) {
+					if (focusHighlightIndex >= 0) {
+						if (focusHighlightIndex === nodeData.highlightIndex) {
+							highlightElement(node, nodeData.highlightIndex, parentIframe)
+						}
+					} else {
+						highlightElement(node, nodeData.highlightIndex, parentIframe)
+					}
+					return true // Successfully highlighted
+				}
+			} else {
+				// console.log(`Skipping highlight for ${nodeData.tagName} (outside viewport)`);
+			}
+		}
+
+		return false // Did not highlight
+	}
+
+	/**
+	 * Creates a node data object for a given node and its descendants.
+	 *
+	 * @param {HTMLElement} node - The node to process.
+	 * @param {HTMLElement | null} parentIframe - The parent iframe node.
+	 * @param {boolean} isParentHighlighted - Whether the parent node is highlighted.
+	 * @returns {string | null} The ID of the node data object, or null if the node is not processed.
+	 */
+	function buildDomTree(node, parentIframe = null, isParentHighlighted = false) {
+		// Fast rejection checks first
+		if (
+			!node ||
+			node.id === HIGHLIGHT_CONTAINER_ID ||
+			(node.nodeType !== Node.ELEMENT_NODE && node.nodeType !== Node.TEXT_NODE)
+		) {
+			return null
+		}
+
+		if (!node || node.id === HIGHLIGHT_CONTAINER_ID) {
+			return null
+		}
+
+		/**
+		 * @edit add `data-browser-use-ignore` attribute
+		 */
+		if (node.dataset?.browserUseIgnore === 'true' || node.dataset?.pageAgentIgnore === 'true') {
+			return null // Skip this node and its children
+		}
+
+		/**
+		 * @edit exclude aria-hidden elements
+		 */
+		if (node.getAttribute && node.getAttribute('aria-hidden') === 'true') {
+			return null // Skip this node and its children
+		}
+
+		// Special handling for root node (body)
+		if (node === document.body) {
+			const nodeData = {
+				tagName: 'body',
+				attributes: {},
+				xpath: '/body',
+				children: [],
+			}
+
+			// Process children of body
+			for (const child of node.childNodes) {
+				const domElement = buildDomTree(child, parentIframe, false) // Body's children have no highlighted parent initially
+				if (domElement) nodeData.children.push(domElement)
+			}
+
+			const id = `${ID.current++}`
+			DOM_HASH_MAP[id] = nodeData
+			return id
+		}
+
+		// Early bailout for non-element nodes except text
+		if (node.nodeType !== Node.ELEMENT_NODE && node.nodeType !== Node.TEXT_NODE) {
+			return null
+		}
+
+		// Process text nodes
+		if (node.nodeType === Node.TEXT_NODE) {
+			const textContent = node.textContent?.trim()
+			if (!textContent) {
+				return null
+			}
+
+			// Only check visibility for text nodes that might be visible
+			const parentElement = node.parentElement
+			if (!parentElement || parentElement.tagName.toLowerCase() === 'script') {
+				return null
+			}
+
+			const id = `${ID.current++}`
+			DOM_HASH_MAP[id] = {
+				type: 'TEXT_NODE',
+				text: textContent,
+				isVisible: isTextNodeVisible(node),
+			}
+			return id
+		}
+
+		// Quick checks for element nodes
+		if (node.nodeType === Node.ELEMENT_NODE && !isElementAccepted(node)) {
+			return null
+		}
+
+		// Early viewport check - only filter out elements clearly outside viewport
+		// The getBoundingClientRect() of the Shadow DOM host element may return width/height = 0
+		if (viewportExpansion !== -1 && !node.shadowRoot) {
+			const rect = getCachedBoundingRect(node) // Keep for initial quick check
+			const style = getCachedComputedStyle(node)
+
+			// Skip viewport check for fixed/sticky elements as they may appear anywhere
+			const isFixedOrSticky = style && (style.position === 'fixed' || style.position === 'sticky')
+
+			// Check if element has actual dimensions using offsetWidth/Height (quick check)
+			const hasSize = node.offsetWidth > 0 || node.offsetHeight > 0
+
+			// Use getBoundingClientRect for the quick OUTSIDE check.
+			// isInExpandedViewport will do the more accurate check later if needed.
+			if (
+				!rect ||
+				(!isFixedOrSticky &&
+					!hasSize &&
+					(rect.bottom < -viewportExpansion ||
+						rect.top > window.innerHeight + viewportExpansion ||
+						rect.right < -viewportExpansion ||
+						rect.left > window.innerWidth + viewportExpansion))
+			) {
+				// console.log("Skipping node outside viewport (quick check):", node.tagName, rect);
+				return null
+			}
+		}
+
+		/**
+     * @type {
+      {
+          tagName: string;
+          attributes: Record<string, string | null>;
+          xpath: any;
+          children: never[];
+          isVisible?: boolean;
+          isTopElement?: boolean;
+          isInteractive?: boolean;
+          isInViewport?: boolean;
+          highlightIndex?: number;
+          shadowRoot?: boolean;
+      }
+    } nodeData - The node data object.
+     */
+		const nodeData = {
+			tagName: node.tagName.toLowerCase(),
+			attributes: {},
+
+			/**
+			 * @edit no need for xpath
+			 */
+			// xpath: getXPathTree(node, true),
+
+			children: [],
+		}
+
+		// Get attributes for interactive elements or potential text containers
+		if (
+			isInteractiveCandidate(node) ||
+			node.tagName.toLowerCase() === 'iframe' ||
+			node.tagName.toLowerCase() === 'body'
+		) {
+			const attributeNames = node.getAttributeNames?.() || []
+			for (const name of attributeNames) {
+				const value = node.getAttribute(name)
+				nodeData.attributes[name] = value
+			}
+
+			/**
+			 * @edit @workaround input.checked
+			 */
+			if (
+				node.tagName.toLowerCase() === 'input' &&
+				(node.type === 'checkbox' || node.type === 'radio')
+			) {
+				nodeData.attributes.checked = node.checked ? 'true' : 'false' // Store as string for consistency
+			}
+		}
+
+		let nodeWasHighlighted = false
+		// Perform visibility, interactivity, and highlighting checks
+		if (node.nodeType === Node.ELEMENT_NODE) {
+			nodeData.isVisible = isElementVisible(node) // isElementVisible uses offsetWidth/Height, which is fine
+			if (nodeData.isVisible) {
+				nodeData.isTopElement = isTopElement(node)
+
+				// Special handling for ARIA menu containers - check interactivity even if not top element
+				const role = node.getAttribute('role')
+				const isMenuContainer = role === 'menu' || role === 'menubar' || role === 'listbox'
+
+				if (nodeData.isTopElement || isMenuContainer) {
+					nodeData.isInteractive = isInteractiveElement(node)
+					// Call the dedicated highlighting function
+					nodeWasHighlighted = handleHighlighting(nodeData, node, parentIframe, isParentHighlighted)
+
+					/**
+					 * @edit direct dom ref
+					 */
+					nodeData.ref = node
+
+					/**
+					 * @edit make sure attributes exist for interactive candidates.
+					 * @note if the element failed the isInteractiveCandidate, attributes would be empty.
+					 */
+					if (nodeData.isInteractive && Object.keys(nodeData.attributes).length === 0) {
+						const attributeNames = node.getAttributeNames?.() || []
+						for (const name of attributeNames) {
+							const value = node.getAttribute(name)
+							nodeData.attributes[name] = value
+						}
+					}
+				}
+			}
+		}
+
+		// Process children, with special handling for iframes and rich text editors
+		if (node.tagName) {
+			const tagName = node.tagName.toLowerCase()
+
+			// Handle iframes
+			if (tagName === 'iframe') {
+				try {
+					const iframeDoc = node.contentDocument || node.contentWindow?.document
+					if (iframeDoc) {
+						for (const child of iframeDoc.childNodes) {
+							const domElement = buildDomTree(child, node, false)
+							if (domElement) nodeData.children.push(domElement)
+						}
+					}
+				} catch (e) {
+					console.warn('Unable to access iframe:', e)
+				}
+			}
+			// Handle rich text editors and contenteditable elements
+			else if (
+				node.isContentEditable ||
+				node.getAttribute('contenteditable') === 'true' ||
+				node.id === 'tinymce' ||
+				node.classList.contains('mce-content-body') ||
+				(tagName === 'body' && node.getAttribute('data-id')?.startsWith('mce_'))
+			) {
+				// Process all child nodes to capture formatted text
+				for (const child of node.childNodes) {
+					const domElement = buildDomTree(child, parentIframe, nodeWasHighlighted)
+					if (domElement) nodeData.children.push(domElement)
+				}
+			} else {
+				// Handle shadow DOM
+				if (node.shadowRoot) {
+					nodeData.shadowRoot = true
+					for (const child of node.shadowRoot.childNodes) {
+						const domElement = buildDomTree(child, parentIframe, nodeWasHighlighted)
+						if (domElement) nodeData.children.push(domElement)
+					}
+				}
+				// Handle regular elements
+				for (const child of node.childNodes) {
+					// Pass the highlighted status of the *current* node to its children
+					const passHighlightStatusToChild = nodeWasHighlighted || isParentHighlighted
+					const domElement = buildDomTree(child, parentIframe, passHighlightStatusToChild)
+					if (domElement) nodeData.children.push(domElement)
+				}
+			}
+		}
+
+		// Skip empty anchor tags only if they have no dimensions and no children
+		if (nodeData.tagName === 'a' && nodeData.children.length === 0 && !nodeData.attributes.href) {
+			// Check if the anchor has actual dimensions
+			const rect = getCachedBoundingRect(node)
+			const hasSize =
+				(rect && rect.width > 0 && rect.height > 0) || node.offsetWidth > 0 || node.offsetHeight > 0
+
+			if (!hasSize) {
+				return null
+			}
+		}
+
+		/**
+		 * @edit add `extra` field for extra data
+		 */
+		nodeData.extra = extraData.get(node) || null
+
+		const id = `${ID.current++}`
+		DOM_HASH_MAP[id] = nodeData
+		return id
+	}
+
+	const rootId = buildDomTree(document.body)
+
+	// Clear the cache before starting
+	DOM_CACHE.clearCache()
+
+	return { rootId, map: DOM_HASH_MAP }
+}
diff --git a/packages/page-controller/src/dom/dom_tree/type.ts b/packages/page-controller/src/dom/dom_tree/type.ts
new file mode 100644
index 0000000..1932e95
--- /dev/null
+++ b/packages/page-controller/src/dom/dom_tree/type.ts
@@ -0,0 +1,51 @@
+// FlatDomTree: 扁平化 DOM 树结构，适用于高效存储和遍历页面结构。
+// 每个节点通过 map 索引，支持文本节点和元素节点，字段区分 undefined 和 false。
+
+export interface FlatDomTree {
+	rootId: string
+	map: Record<string, DomNode>
+}
+
+export type DomNode = TextDomNode | ElementDomNode | InteractiveElementDomNode
+
+export interface TextDomNode {
+	type: 'TEXT_NODE'
+	text: string
+	isVisible: boolean
+	// 其他可选字段
+	[key: string]: unknown
+}
+
+export interface ElementDomNode {
+	tagName: string
+	attributes?: Record<string, string>
+	xpath?: string
+	children?: string[]
+	isVisible?: boolean
+	isTopElement?: boolean
+	isInViewport?: boolean
+	isNew?: boolean
+	isInteractive?: false
+	highlightIndex?: number
+	extra?: Record<string, any>
+	// 其他可选字段
+	[key: string]: unknown
+}
+
+export interface InteractiveElementDomNode {
+	tagName: string
+	attributes?: Record<string, string>
+	xpath?: string
+	children?: string[]
+	isVisible?: boolean
+	isTopElement?: boolean
+	isInViewport?: boolean
+	isInteractive: true
+	highlightIndex: number
+	/**
+	 * 可交互元素的 dom 引用
+	 */
+	ref: HTMLElement
+	// 其他可选字段
+	[key: string]: unknown
+}
diff --git a/packages/page-controller/src/dom/getPageInfo.ts b/packages/page-controller/src/dom/getPageInfo.ts
new file mode 100644
index 0000000..61abe82
--- /dev/null
+++ b/packages/page-controller/src/dom/getPageInfo.ts
@@ -0,0 +1,42 @@
+export function getPageInfo() {
+	const viewport_width = window.innerWidth
+	const viewport_height = window.innerHeight
+
+	const page_width = Math.max(document.documentElement.scrollWidth, document.body.scrollWidth || 0)
+	const page_height = Math.max(
+		document.documentElement.scrollHeight,
+		document.body.scrollHeight || 0
+	)
+
+	const scroll_x = window.scrollX || window.pageXOffset || document.documentElement.scrollLeft || 0
+	const scroll_y = window.scrollY || window.pageYOffset || document.documentElement.scrollTop || 0
+
+	const pixels_below = Math.max(0, page_height - (window.innerHeight + scroll_y))
+	const pixels_right = Math.max(0, page_width - (window.innerWidth + scroll_x))
+
+	return {
+		// Current viewport dimensions
+		viewport_width,
+		viewport_height,
+
+		// Total page dimensions
+		page_width,
+		page_height,
+
+		// Current scroll position
+		scroll_x,
+		scroll_y,
+
+		pixels_above: scroll_y,
+		pixels_below,
+
+		pages_above: viewport_height > 0 ? scroll_y / viewport_height : 0,
+		pages_below: viewport_height > 0 ? pixels_below / viewport_height : 0,
+		total_pages: viewport_height > 0 ? page_height / viewport_height : 0,
+
+		current_page_position: scroll_y / Math.max(1, page_height - viewport_height),
+
+		pixels_left: scroll_x,
+		pixels_right,
+	}
+}
diff --git a/packages/page-controller/src/dom/index.ts b/packages/page-controller/src/dom/index.ts
new file mode 100644
index 0000000..a7ae7f8
--- /dev/null
+++ b/packages/page-controller/src/dom/index.ts
@@ -0,0 +1,569 @@
+import domTree from './dom_tree/index.js'
+import {
+	ElementDomNode,
+	FlatDomTree,
+	InteractiveElementDomNode,
+	TextDomNode,
+} from './dom_tree/type'
+
+/**
+ * Viewport expansion for DOM tree extraction.
+ * -1 means full page (no viewport restriction)
+ * 0 means viewport only
+ * positive values expand the viewport by that many pixels
+ *
+ * @note Since isTopElement depends on elementFromPoint,
+ * it returns null when out of viewport, this feature has no practical use, only differ between -1 and 0
+ */
+const DEFAULT_VIEWPORT_EXPANSION = -1
+
+export function resolveViewportExpansion(viewportExpansion?: number): number {
+	return viewportExpansion ?? DEFAULT_VIEWPORT_EXPANSION
+}
+
+export interface DomConfig {
+	viewportExpansion?: number
+	interactiveBlacklist?: (Element | (() => Element))[]
+	interactiveWhitelist?: (Element | (() => Element))[]
+	includeAttributes?: string[]
+	highlightOpacity?: number
+	highlightLabelOpacity?: number
+
+	/**
+	 * Preserve semantic landmark tags in dehydrated output even if not interactive
+	 * @note maybe confusing for LLM combining with page scrolling, use with caution
+	 **/
+	keepSemanticTags?: boolean
+}
+
+// TODO: corresponding roles
+const SEMANTIC_TAGS = new Set([
+	'nav',
+	'menu',
+	// 'main',
+	'header',
+	'footer',
+	'aside',
+	// 'article',
+	// 'form',
+	'dialog',
+])
+
+/**
+ * 用于检测可交互元素是否是新出现的。
+ */
+const newElementsCache = new WeakMap<HTMLElement, string>()
+
+export function getFlatTree(config: DomConfig): FlatDomTree {
+	const viewportExpansion = resolveViewportExpansion(config.viewportExpansion)
+
+	const interactiveBlacklist = [] as Element[]
+	for (const item of config.interactiveBlacklist || []) {
+		if (typeof item === 'function') {
+			interactiveBlacklist.push(item())
+		} else {
+			interactiveBlacklist.push(item)
+		}
+	}
+
+	const interactiveWhitelist = [] as Element[]
+	for (const item of config.interactiveWhitelist || []) {
+		if (typeof item === 'function') {
+			interactiveWhitelist.push(item())
+		} else {
+			interactiveWhitelist.push(item)
+		}
+	}
+
+	const elements = domTree({
+		doHighlightElements: true,
+		debugMode: true,
+		focusHighlightIndex: -1,
+		viewportExpansion,
+		interactiveBlacklist,
+		interactiveWhitelist,
+		highlightOpacity: config.highlightOpacity ?? 0.0,
+		highlightLabelOpacity: config.highlightLabelOpacity ?? 0.1,
+	}) as FlatDomTree
+
+	const currentUrl = window.location.href
+
+	/**
+	 * 标记新出现的元素
+	 * @todo browser-use 使用 hash(位置，属性等信息) 来判断是否同一个元素，
+	 *       能够解决 1. 元素被删除后重新添加 2. 页面卸载 等问题。
+	 *       这里先简单做.
+	 */
+	for (const nodeId in elements.map) {
+		const node = elements.map[nodeId]
+		if (node.isInteractive && node.ref) {
+			const ref = node.ref as HTMLElement
+			// @note 这样太严格，元素是可以跨页面存在的
+			// if (newElementsCache.get(ref) !== currentUrl) {
+			if (!newElementsCache.has(ref)) {
+				newElementsCache.set(ref, currentUrl)
+				node.isNew = true
+			}
+		}
+	}
+
+	return elements
+}
+
+const globRegexCache = new Map<string, RegExp>()
+
+function globToRegex(pattern: string): RegExp {
+	let regex = globRegexCache.get(pattern)
+	if (!regex) {
+		const escaped = pattern.replace(/[.+^${}()|[\]\\]/g, '\\$&')
+		regex = new RegExp(`^${escaped.replace(/\*/g, '.*')}$`)
+		globRegexCache.set(pattern, regex)
+	}
+	return regex
+}
+
+function matchAttributes(
+	attrs: Record<string, string>,
+	patterns: string[]
+): Record<string, string> {
+	const result: Record<string, string> = {}
+
+	for (const pattern of patterns) {
+		if (pattern.includes('*')) {
+			const regex = globToRegex(pattern)
+			for (const key of Object.keys(attrs)) {
+				if (regex.test(key) && attrs[key].trim()) {
+					result[key] = attrs[key].trim()
+				}
+			}
+		} else {
+			const value = attrs[pattern]
+			if (value && value.trim()) {
+				result[pattern] = value.trim()
+			}
+		}
+	}
+
+	return result
+}
+
+/**
+ * elementsToString 内部使用的类型
+ */
+interface TreeNode {
+	type: 'text' | 'element'
+	parent: TreeNode | null
+	children: TreeNode[]
+	isVisible: boolean
+	// Text node properties
+	text?: string
+	// Element node properties
+	tagName?: string
+	attributes?: Record<string, string>
+	isInteractive?: boolean
+	isTopElement?: boolean
+	isNew?: boolean
+	highlightIndex?: number
+	extra?: Record<string, any>
+}
+
+/**
+ * 对应 python 中的 views::clickable_elements_to_string,
+ * 将 dom 信息处理成适合 llm 阅读的文本格式
+ * @形如
+ * ``` text
+ * [0]<a aria-label=page-agent.js 首页 />
+ * [1]<div >P />
+ * [2]<div >page-agent.js
+ * UI Agent in your webpage />
+ * [3]<a >文档 />
+ * [4]<a aria-label=查看源码（在新窗口打开）>源码 />
+ * UI Agent in your webpage
+ * 用户输入需求，AI 理解页面并自动操作。
+ * [5]<a role=button>快速开始 />
+ * [6]<a role=button>查看文档 />
+ * 无需后端
+ * ```
+ * 其中可交互元素用序号标出，提示llm可以用序号操作。
+ * 缩进代表父子关系。
+ * 普通文本则直接列出来。
+ *
+ * @todo 数据脱敏过滤器
+ */
+export function flatTreeToString(
+	flatTree: FlatDomTree,
+	includeAttributes: string[] = [],
+	keepSemanticTags = false
+): string {
+	const DEFAULT_INCLUDE_ATTRIBUTES = [
+		'title',
+		'type',
+		'checked',
+		'name',
+		'role',
+		'value',
+		'placeholder',
+		'data-date-format',
+		'alt',
+		'aria-label',
+		'aria-expanded',
+		'data-state',
+		'aria-checked',
+
+		// @edit added for better form handling
+		'id',
+		'for',
+
+		// for jump check
+		'target',
+
+		// absolute position dropdown menu
+		'aria-haspopup',
+		'aria-controls',
+		'aria-owns',
+
+		// content editable
+		'contenteditable',
+	]
+
+	const includeAttrs = [...includeAttributes, ...DEFAULT_INCLUDE_ATTRIBUTES]
+
+	// Helper function to cap text length
+	const capTextLength = (text: string, maxLength: number): string => {
+		if (text.length > maxLength) {
+			return text.substring(0, maxLength) + '...'
+		}
+		return text
+	}
+
+	// Build tree structure from flat map
+	const buildTreeNode = (nodeId: string): TreeNode | null => {
+		const node = flatTree.map[nodeId]
+		if (!node) return null
+
+		if (node.type === 'TEXT_NODE') {
+			const textNode = node as TextDomNode
+			return {
+				type: 'text',
+				text: textNode.text,
+				isVisible: textNode.isVisible,
+				parent: null,
+				children: [],
+			}
+		} else {
+			const elementNode = node as ElementDomNode
+			const children: TreeNode[] = []
+
+			if (elementNode.children) {
+				for (const childId of elementNode.children) {
+					const child = buildTreeNode(childId)
+					if (child) {
+						child.parent = null // Will be set later
+						children.push(child)
+					}
+				}
+			}
+
+			return {
+				type: 'element',
+				tagName: elementNode.tagName,
+				attributes: elementNode.attributes ?? {},
+				isVisible: elementNode.isVisible ?? false,
+				isInteractive: elementNode.isInteractive ?? false,
+				isTopElement: elementNode.isTopElement ?? false,
+				isNew: elementNode.isNew ?? false,
+				highlightIndex: elementNode.highlightIndex,
+				parent: null,
+				children,
+				extra: elementNode.extra ?? {},
+			}
+		}
+	}
+
+	// Set parent references
+	const setParentReferences = (node: TreeNode, parent: TreeNode | null = null) => {
+		node.parent = parent
+		for (const child of node.children) {
+			setParentReferences(child, node)
+		}
+	}
+
+	// Build root node
+	const rootNode = buildTreeNode(flatTree.rootId)
+	if (!rootNode) return ''
+
+	setParentReferences(rootNode)
+
+	// Helper to check if text node has parent with highlight index
+	const hasParentWithHighlightIndex = (node: TreeNode): boolean => {
+		let current = node.parent
+		while (current) {
+			if (current.type === 'element' && current.highlightIndex !== undefined) {
+				return true
+			}
+			current = current.parent
+		}
+		return false
+	}
+
+	// Helper to check if parent is top element
+	// const isParentTopElement = (node: TreeNode): boolean => {
+	// 	return node.parent?.type === 'element' && node.parent.isTopElement === true
+	// }
+
+	// Main processing function
+	const processNode = (node: TreeNode, depth: number, result: string[]): void => {
+		let nextDepth = depth
+		const depthStr = '\t'.repeat(depth)
+
+		if (node.type === 'element') {
+			const isSemantic = keepSemanticTags && node.tagName && SEMANTIC_TAGS.has(node.tagName)
+
+			// Add element with highlight_index
+			if (node.highlightIndex !== undefined) {
+				nextDepth += 1
+
+				const text = getAllTextTillNextClickableElement(node)
+				let attributesHtmlStr = ''
+
+				if (includeAttrs.length > 0 && node.attributes) {
+					const attributesToInclude = matchAttributes(node.attributes, includeAttrs)
+
+					// Remove duplicate values (for attributes longer than 5 chars)
+					const keys = Object.keys(attributesToInclude)
+					if (keys.length > 1) {
+						const keysToRemove = new Set<string>()
+						const seenValues: Record<string, string> = {}
+
+						for (const key of keys) {
+							const value = attributesToInclude[key]
+							if (value.length > 5) {
+								if (value in seenValues) {
+									keysToRemove.add(key)
+								} else {
+									seenValues[value] = key
+								}
+							}
+						}
+
+						for (const key of keysToRemove) {
+							delete attributesToInclude[key]
+						}
+					}
+
+					// Remove role if it matches tagName
+					if (attributesToInclude.role === node.tagName) {
+						delete attributesToInclude.role
+					}
+
+					// Remove attributes that duplicate text content
+					const attrsToRemoveIfTextMatches = ['aria-label', 'placeholder', 'title']
+					for (const attr of attrsToRemoveIfTextMatches) {
+						if (
+							attributesToInclude[attr] &&
+							attributesToInclude[attr].toLowerCase().trim() === text.toLowerCase().trim()
+						) {
+							delete attributesToInclude[attr]
+						}
+					}
+
+					if (Object.keys(attributesToInclude).length > 0) {
+						attributesHtmlStr = Object.entries(attributesToInclude)
+							.map(([key, value]) => `${key}=${capTextLength(value, 20)}`)
+							.join(' ')
+					}
+				}
+
+				// Build the line
+				const highlightIndicator = node.isNew
+					? `*[${node.highlightIndex}]`
+					: `[${node.highlightIndex}]`
+				let line = `${depthStr}${highlightIndicator}<${node.tagName ?? ''}`
+
+				if (attributesHtmlStr) {
+					line += ` ${attributesHtmlStr}`
+				}
+
+				/**
+				 * @edit scrollable 数据
+				 */
+				if (node.extra) {
+					if (node.extra.scrollable) {
+						let scrollDataText = ''
+						if (node.extra.scrollData?.left)
+							scrollDataText += `left=${node.extra.scrollData.left}, `
+						if (node.extra.scrollData?.top) scrollDataText += `top=${node.extra.scrollData.top}, `
+						if (node.extra.scrollData?.right)
+							scrollDataText += `right=${node.extra.scrollData.right}, `
+						if (node.extra.scrollData?.bottom)
+							scrollDataText += `bottom=${node.extra.scrollData.bottom}`
+
+						line += ` data-scrollable="${scrollDataText}"`
+					}
+				}
+
+				if (text) {
+					const trimmedText = text.trim()
+					if (!attributesHtmlStr) {
+						line += ' '
+					}
+					line += `>${trimmedText}`
+				} else if (!attributesHtmlStr) {
+					line += ' '
+				}
+
+				line += ' />'
+				result.push(line)
+			}
+
+			// special treatment for semantic tags
+			// even if they are not interactive, we can keep them for clear context
+
+			const emitSemantic = isSemantic && node.highlightIndex === undefined
+			// to check if this tag is empty
+			const mark = emitSemantic ? result.length : -1
+
+			if (emitSemantic) {
+				result.push(`${depthStr}<${node.tagName}>`)
+				nextDepth += 1
+			}
+
+			for (const child of node.children) {
+				processNode(child, nextDepth, result)
+			}
+
+			if (emitSemantic) {
+				// empty tag should be removed
+				if (result.length === mark + 1) {
+					result.pop()
+				} else {
+					result.push(`${depthStr}</${node.tagName}>`)
+				}
+			}
+		} else if (node.type === 'text') {
+			// Add text only if it doesn't have a highlighted parent
+			if (hasParentWithHighlightIndex(node)) {
+				return
+			}
+
+			if (
+				node.parent &&
+				node.parent.type === 'element' &&
+				node.parent.isVisible &&
+				node.parent.isTopElement
+			) {
+				result.push(`${depthStr}${node.text ?? ''}`)
+			}
+		}
+	}
+
+	const result: string[] = []
+	processNode(rootNode, 0, result)
+	return result.join('\n')
+}
+
+// Get all text until next clickable element
+export const getAllTextTillNextClickableElement = (node: TreeNode, maxDepth = -1): string => {
+	const textParts: string[] = []
+
+	const collectText = (currentNode: TreeNode, currentDepth: number) => {
+		if (maxDepth !== -1 && currentDepth > maxDepth) {
+			return
+		}
+
+		// Skip this branch if we hit a highlighted element (except for the current node)
+		if (
+			currentNode.type === 'element' &&
+			currentNode !== node &&
+			currentNode.highlightIndex !== undefined
+		) {
+			return
+		}
+
+		if (currentNode.type === 'text' && currentNode.text) {
+			textParts.push(currentNode.text)
+		} else if (currentNode.type === 'element') {
+			for (const child of currentNode.children) {
+				collectText(child, currentDepth + 1)
+			}
+		}
+	}
+
+	collectText(node, 0)
+	return textParts.join('\n').trim()
+}
+
+export function getSelectorMap(flatTree: FlatDomTree): Map<number, InteractiveElementDomNode> {
+	const selectorMap = new Map<number, InteractiveElementDomNode>()
+
+	const keys = Object.keys(flatTree.map)
+	for (const key of keys) {
+		const node = flatTree.map[key]
+		if (node.isInteractive && typeof node.highlightIndex === 'number') {
+			selectorMap.set(node.highlightIndex, node as InteractiveElementDomNode)
+		}
+	}
+
+	return selectorMap
+}
+
+export function getElementTextMap(simplifiedHTML: string) {
+	const lines = simplifiedHTML
+		.split('\n')
+		.map((line) => line.trim())
+		.filter((line) => line.length > 0)
+	const elementTextMap = new Map<number, string>()
+	for (const line of lines) {
+		const regex = /^\[(\d+)\]<[^>]+>([^<]*)/
+		const match = regex.exec(line)
+		if (match) {
+			const index = parseInt(match[1], 10)
+			elementTextMap.set(index, line)
+		}
+	}
+
+	return elementTextMap
+}
+
+export function cleanUpHighlights() {
+	const cleanupFunctions = (window as any)._highlightCleanupFunctions || []
+	for (const cleanup of cleanupFunctions) {
+		if (typeof cleanup === 'function') {
+			cleanup()
+		}
+	}
+
+	;(window as any)._highlightCleanupFunctions = []
+}
+
+// 监听 URL 的任何变化，立刻清空 highLights
+window.addEventListener('popstate', () => {
+	// console.log('URL changed (popstate), highlights cleaned up.')
+	cleanUpHighlights()
+})
+window.addEventListener('hashchange', () => {
+	// console.log('URL changed (hashchange), highlights cleaned up.')
+	cleanUpHighlights()
+})
+window.addEventListener('beforeunload', () => {
+	// console.log('Page is unloading, highlights cleaned up.')
+	cleanUpHighlights()
+})
+
+const navigation = (window as any).navigation
+if (navigation && typeof navigation.addEventListener === 'function') {
+	navigation.addEventListener('navigate', () => {
+		// console.log('Navigation event detected, highlights cleaned up.')
+		cleanUpHighlights()
+	})
+} else {
+	// 定时器
+	let currentUrl = window.location.href
+	setInterval(() => {
+		if (window.location.href !== currentUrl) {
+			currentUrl = window.location.href
+			// console.log('URL changed (interval), highlights cleaned up.')
+			cleanUpHighlights()
+		}
+	}, 500)
+}
diff --git a/packages/page-controller/src/env.d.ts b/packages/page-controller/src/env.d.ts
new file mode 100644
index 0000000..10798a0
--- /dev/null
+++ b/packages/page-controller/src/env.d.ts
@@ -0,0 +1,6 @@
+/// <reference types="vite/client" />
+
+declare module '*.module.css' {
+	const classes: Record<string, string>
+	export default classes
+}
diff --git a/packages/page-controller/src/mask/SimulatorMask.module.css b/packages/page-controller/src/mask/SimulatorMask.module.css
new file mode 100644
index 0000000..7b73e05
--- /dev/null
+++ b/packages/page-controller/src/mask/SimulatorMask.module.css
@@ -0,0 +1,13 @@
+.wrapper {
+	position: fixed;
+	inset: 0;
+	z-index: 2147483641; /* 确保在所有元素之上，除了 panel */
+	cursor: wait;
+	overflow: hidden;
+
+	display: none;
+}
+
+.wrapper.visible {
+	display: block;
+}
diff --git a/packages/page-controller/src/mask/SimulatorMask.ts b/packages/page-controller/src/mask/SimulatorMask.ts
new file mode 100644
index 0000000..d507f6e
--- /dev/null
+++ b/packages/page-controller/src/mask/SimulatorMask.ts
@@ -0,0 +1,216 @@
+import { Motion } from 'ai-motion'
+
+import { isPageDark } from './checkDarkMode'
+
+import styles from './SimulatorMask.module.css'
+import cursorStyles from './cursor.module.css'
+
+export class SimulatorMask extends EventTarget {
+	shown: boolean = false
+	wrapper = document.createElement('div')
+	motion: Motion | null = null
+
+	#disposed = false
+
+	#cursor = document.createElement('div')
+
+	#currentCursorX = 0
+	#currentCursorY = 0
+
+	#targetCursorX = 0
+	#targetCursorY = 0
+
+	constructor() {
+		super()
+
+		this.wrapper.id = 'page-agent-runtime_simulator-mask'
+		this.wrapper.className = styles.wrapper
+		this.wrapper.setAttribute('data-browser-use-ignore', 'true')
+		this.wrapper.setAttribute('data-page-agent-ignore', 'true')
+
+		try {
+			const motion = new Motion({
+				mode: isPageDark() ? 'dark' : 'light',
+				styles: { position: 'absolute', inset: '0' },
+			})
+			this.motion = motion
+			this.wrapper.appendChild(motion.element)
+			motion.autoResize(this.wrapper)
+		} catch (e) {
+			console.warn('[SimulatorMask] Motion overlay unavailable:', e)
+		}
+
+		// Capture all mouse, keyboard, and wheel events
+		this.wrapper.addEventListener('click', (e) => {
+			e.stopPropagation()
+			e.preventDefault()
+		})
+		this.wrapper.addEventListener('mousedown', (e) => {
+			e.stopPropagation()
+			e.preventDefault()
+		})
+		this.wrapper.addEventListener('mouseup', (e) => {
+			e.stopPropagation()
+			e.preventDefault()
+		})
+		this.wrapper.addEventListener('mousemove', (e) => {
+			e.stopPropagation()
+			e.preventDefault()
+		})
+		this.wrapper.addEventListener('wheel', (e) => {
+			e.stopPropagation()
+			e.preventDefault()
+		})
+		this.wrapper.addEventListener('keydown', (e) => {
+			e.stopPropagation()
+			e.preventDefault()
+		})
+		this.wrapper.addEventListener('keyup', (e) => {
+			e.stopPropagation()
+			e.preventDefault()
+		})
+
+		// Create AI cursor
+		this.#createCursor()
+		// this.show()
+
+		document.body.appendChild(this.wrapper)
+
+		this.#moveCursorToTarget()
+
+		// global events
+		// @note Mask should be isolated from the rest of the code.
+		// Global events are easier to manage and cleanup.
+
+		const movePointerToListener = (event: Event) => {
+			const { x, y } = (event as CustomEvent).detail
+			this.setCursorPosition(x, y)
+		}
+		const clickPointerListener = () => {
+			this.triggerClickAnimation()
+		}
+		const enablePassThroughListener = () => {
+			this.wrapper.style.pointerEvents = 'none'
+		}
+		const disablePassThroughListener = () => {
+			this.wrapper.style.pointerEvents = 'auto'
+		}
+
+		window.addEventListener('PageAgent::MovePointerTo', movePointerToListener)
+		window.addEventListener('PageAgent::ClickPointer', clickPointerListener)
+		window.addEventListener('PageAgent::EnablePassThrough', enablePassThroughListener)
+		window.addEventListener('PageAgent::DisablePassThrough', disablePassThroughListener)
+
+		this.addEventListener('dispose', () => {
+			window.removeEventListener('PageAgent::MovePointerTo', movePointerToListener)
+			window.removeEventListener('PageAgent::ClickPointer', clickPointerListener)
+			window.removeEventListener('PageAgent::EnablePassThrough', enablePassThroughListener)
+			window.removeEventListener('PageAgent::DisablePassThrough', disablePassThroughListener)
+		})
+	}
+
+	#createCursor() {
+		this.#cursor.className = cursorStyles.cursor
+
+		// Create ripple effect container
+		const rippleContainer = document.createElement('div')
+		rippleContainer.className = cursorStyles.cursorRipple
+		this.#cursor.appendChild(rippleContainer)
+
+		// Create filling layer
+		const fillingLayer = document.createElement('div')
+		fillingLayer.className = cursorStyles.cursorFilling
+		this.#cursor.appendChild(fillingLayer)
+
+		// Create border layer
+		const borderLayer = document.createElement('div')
+		borderLayer.className = cursorStyles.cursorBorder
+		this.#cursor.appendChild(borderLayer)
+
+		this.wrapper.appendChild(this.#cursor)
+	}
+
+	#moveCursorToTarget() {
+		if (this.#disposed) return
+
+		const newX = this.#currentCursorX + (this.#targetCursorX - this.#currentCursorX) * 0.2
+		const newY = this.#currentCursorY + (this.#targetCursorY - this.#currentCursorY) * 0.2
+
+		const xDistance = Math.abs(newX - this.#targetCursorX)
+		if (xDistance > 0) {
+			if (xDistance < 2) {
+				this.#currentCursorX = this.#targetCursorX
+			} else {
+				this.#currentCursorX = newX
+			}
+			this.#cursor.style.left = `${this.#currentCursorX}px`
+		}
+
+		const yDistance = Math.abs(newY - this.#targetCursorY)
+		if (yDistance > 0) {
+			if (yDistance < 2) {
+				this.#currentCursorY = this.#targetCursorY
+			} else {
+				this.#currentCursorY = newY
+			}
+			this.#cursor.style.top = `${this.#currentCursorY}px`
+		}
+
+		requestAnimationFrame(() => this.#moveCursorToTarget())
+	}
+
+	setCursorPosition(x: number, y: number) {
+		if (this.#disposed) return
+
+		this.#targetCursorX = x
+		this.#targetCursorY = y
+	}
+
+	triggerClickAnimation() {
+		if (this.#disposed) return
+
+		this.#cursor.classList.remove(cursorStyles.clicking)
+		// Force reflow to restart animation
+		void this.#cursor.offsetHeight
+		this.#cursor.classList.add(cursorStyles.clicking)
+	}
+
+	show() {
+		if (this.shown || this.#disposed) return
+
+		this.shown = true
+		this.motion?.start()
+		this.motion?.fadeIn()
+
+		this.wrapper.classList.add(styles.visible)
+
+		// Initialize cursor position
+		this.#currentCursorX = window.innerWidth / 2
+		this.#currentCursorY = window.innerHeight / 2
+		this.#targetCursorX = this.#currentCursorX
+		this.#targetCursorY = this.#currentCursorY
+		this.#cursor.style.left = `${this.#currentCursorX}px`
+		this.#cursor.style.top = `${this.#currentCursorY}px`
+	}
+
+	hide() {
+		if (!this.shown || this.#disposed) return
+
+		this.shown = false
+		this.motion?.fadeOut()
+		this.motion?.pause()
+
+		this.#cursor.classList.remove(cursorStyles.clicking)
+
+		setTimeout(() => {
+			this.wrapper.classList.remove(styles.visible)
+		}, 800) // Match the animation duration
+	}
+
+	dispose() {
+		this.#disposed = true
+		this.motion?.dispose()
+		this.wrapper.remove()
+		this.dispatchEvent(new Event('dispose'))
+	}
+}
diff --git a/packages/page-controller/src/mask/checkDarkMode.ts b/packages/page-controller/src/mask/checkDarkMode.ts
new file mode 100644
index 0000000..2395fe8
--- /dev/null
+++ b/packages/page-controller/src/mask/checkDarkMode.ts
@@ -0,0 +1,181 @@
+/**
+ * A comprehensive function to determine if the page is currently in a dark theme.
+ * Heuristic check. Only work for common patterns. Return false by default.
+ */
+export function isPageDark() {
+	try {
+		if (hasDarkModeClass()) return true
+		if (hasDarkModeDataAttribute()) return true
+		if (isColorSchemeDark()) return true
+		if (isBackgroundDark()) return true
+		if (isMainContentBackgroundDark()) return true
+		if (isTextColorLight()) return true
+
+		return false
+	} catch (error) {
+		console.warn('Error determining if page is dark:', error)
+		return false
+	}
+}
+
+/**
+ * Checks for common dark mode CSS classes on the html or body elements.
+ */
+function hasDarkModeClass() {
+	const DEFAULT_DARK_MODE_CLASSES = ['dark', 'dark-mode', 'theme-dark', 'night', 'night-mode']
+
+	const htmlElement = document.documentElement
+	const bodyElement = document.body || document.documentElement // can be null in some cases
+
+	// Check class names on <html> and <body>
+	for (const className of DEFAULT_DARK_MODE_CLASSES) {
+		if (htmlElement.classList.contains(className) || bodyElement?.classList.contains(className)) {
+			return true
+		}
+	}
+
+	return false
+}
+
+/**
+ * Some UI frameworks use data attributes to indicate theme
+ */
+function hasDarkModeDataAttribute() {
+	const htmlElement = document.documentElement
+	const bodyElement = document.body || document.documentElement // can be null in some cases
+
+	const dataAttrs = ['data-theme', 'data-color-mode', 'data-bs-theme', 'data-mui-color-scheme']
+	for (const attr of dataAttrs) {
+		const bodyValue = bodyElement?.getAttribute(attr)
+		const htmlValue = htmlElement.getAttribute(attr)
+
+		if (bodyValue?.toLowerCase() === 'dark' || htmlValue?.toLowerCase() === 'dark') {
+			return true
+		}
+	}
+
+	return false
+}
+
+/**
+ * Checks the CSS `color-scheme` property and `<meta name="color-scheme">` tag.
+ * Only "dark"/"only dark" counts as dark; "light dark" is ambiguous and ignored.
+ */
+function isColorSchemeDark() {
+	// Check <meta name="color-scheme" content="dark">
+	const meta = document.querySelector<HTMLMetaElement>('meta[name="color-scheme"]')
+	const metaContent = meta?.content.toLowerCase()
+	if (metaContent === 'dark' || metaContent === 'only dark') return true
+
+	// Check the computed color-scheme CSS property on :root
+	const rootStyle = window.getComputedStyle(document.documentElement)
+	const colorScheme = rootStyle.getPropertyValue('color-scheme').trim().toLowerCase()
+	return colorScheme === 'dark' || colorScheme === 'only dark'
+}
+
+/**
+ * Checks the background color of the body element to determine if the page is dark.
+ */
+function isBackgroundDark() {
+	// We check both <html> and <body> because some pages set the color on <html>
+	const htmlStyle = window.getComputedStyle(document.documentElement)
+	const bodyStyle = window.getComputedStyle(document.body || document.documentElement)
+
+	// Get background colors
+	const htmlBgColor = htmlStyle.backgroundColor
+	const bodyBgColor = bodyStyle.backgroundColor
+
+	// The body's background might be transparent, in which case we should
+	// fall back to the html element's background.
+	if (isColorDark(bodyBgColor)) {
+		return true
+	} else if (bodyBgColor === 'transparent' || bodyBgColor.startsWith('rgba(0, 0, 0, 0)')) {
+		return isColorDark(htmlBgColor)
+	}
+
+	return false
+}
+
+/**
+ * Checks if the text color on the body is light, which implies a dark background.
+ */
+function isTextColorLight() {
+	/** Luminance (0-255) above which body text is considered light */
+	const LIGHT_TEXT_LUMINANCE = 200
+
+	const bodyStyle = window.getComputedStyle(document.body || document.documentElement)
+	const luminance = getLuminance(bodyStyle.color)
+
+	// Light text has high luminance (e.g. white text on dark bg)
+	return luminance !== null && luminance > LIGHT_TEXT_LUMINANCE
+}
+
+/**
+ * Checks the background color of major layout elements (#app, #root, etc.).
+ * Many SPAs render into a container that may have its own dark background while
+ * <body> remains transparent.
+ */
+function isMainContentBackgroundDark() {
+	const { innerWidth: vw, innerHeight: vh } = window
+	const minArea = vw * vh * 0.5
+
+	const selectors = ['#app', '#root', '#__next']
+	for (const selector of selectors) {
+		const el = document.querySelector(selector)
+		if (!el) continue
+
+		const rect = el.getBoundingClientRect()
+		if (rect.width * rect.height < minArea) continue
+
+		if (isColorDark(window.getComputedStyle(el).backgroundColor)) return true
+	}
+	return false
+}
+
+// --- utils ---
+
+/**
+ * Parses an RGB or RGBA color string and returns an object with r, g, b properties.
+ * @param {string} colorString - e.g., "rgb(34, 34, 34)" or "rgba(0, 0, 0, 0.5)"
+ * @returns {{r: number, g: number, b: number}|null}
+ */
+function parseRgbColor(colorString: string) {
+	const rgbMatch = /rgba?\((\d+),\s*(\d+),\s*(\d+)/.exec(colorString)
+	if (!rgbMatch) {
+		return null // Not a valid rgb/rgba string
+	}
+	return {
+		r: parseInt(rgbMatch[1]),
+		g: parseInt(rgbMatch[2]),
+		b: parseInt(rgbMatch[3]),
+	}
+}
+
+/**
+ * Calculates the perceived luminance (0-255) of a CSS color string.
+ * @param {string} colorString - e.g., "rgb(50, 50, 50)" or "rgba(0, 0, 0, 0.5)"
+ * @returns {number|null} - The luminance, or null if the color is transparent or unparseable.
+ */
+function getLuminance(colorString: string): number | null {
+	if (!colorString || colorString === 'transparent' || colorString.startsWith('rgba(0, 0, 0, 0)')) {
+		return null // Transparent has no meaningful luminance
+	}
+
+	const rgb = parseRgbColor(colorString)
+	if (!rgb) {
+		return null // Could not parse color
+	}
+
+	// Standard perceived luminance formula
+	return 0.299 * rgb.r + 0.587 * rgb.g + 0.114 * rgb.b
+}
+
+/**
+ * Determines if a color is "dark" based on its calculated luminance.
+ * @param {string} colorString - The CSS color string (e.g., "rgb(50, 50, 50)").
+ * @param {number} threshold - A value between 0 and 255. Colors with luminance below this will be considered dark. Default is 128.
+ */
+function isColorDark(colorString: string, threshold = 128) {
+	const luminance = getLuminance(colorString)
+	return luminance !== null && luminance < threshold
+}
diff --git a/packages/page-controller/src/mask/cursor-border.svg b/packages/page-controller/src/mask/cursor-border.svg
new file mode 100644
index 0000000..4297909
--- /dev/null
+++ b/packages/page-controller/src/mask/cursor-border.svg
@@ -0,0 +1,3 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 100" fill="none">
+  <g><path d="M 15 42 L 15 36.99 Q 15 31.99 23.7 31.99 L 28.05 31.99 Q 32.41 31.99 32.41 21.99 L 32.41 17 Q 32.41 12 41.09 16.95 L 76.31 37.05 Q 85 42 76.31 46.95 L 41.09 67.05 Q 32.41 72 32.41 62.01 L 32.41 57.01 Q 32.41 52.01 23.7 52.01 L 19.35 52.01 Q 15 52.01 15 47.01 Z" fill="none" stroke="#000000" stroke-width="6" stroke-miterlimit="10" style="stroke: light-dark(rgb(0, 0, 0), rgb(255, 255, 255));"/></g>
+</svg>
diff --git a/packages/page-controller/src/mask/cursor-fill.svg b/packages/page-controller/src/mask/cursor-fill.svg
new file mode 100644
index 0000000..f089f5c
--- /dev/null
+++ b/packages/page-controller/src/mask/cursor-fill.svg
@@ -0,0 +1,5 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 100">
+  <defs>
+  </defs>
+  <g xmlns="http://www.w3.org/2000/svg" style="filter: drop-shadow(light-dark(rgba(0, 0, 0, 0.4), rgba(237, 237, 237, 0.4)) 3px 4px 4px);"><path d="M 15 42 L 15 36.99 Q 15 31.99 23.7 31.99 L 28.05 31.99 Q 32.41 31.99 32.41 21.99 L 32.41 17 Q 32.41 12 41.09 16.95 L 76.31 37.05 Q 85 42 76.31 46.95 L 41.09 67.05 Q 32.41 72 32.41 62.01 L 32.41 57.01 Q 32.41 52.01 23.7 52.01 L 19.35 52.01 Q 15 52.01 15 47.01 Z" fill="#ffffff" stroke="none" style="fill: #ffffff;"/></g>
+</svg>
diff --git a/packages/page-controller/src/mask/cursor.module.css b/packages/page-controller/src/mask/cursor.module.css
new file mode 100644
index 0000000..375b9c4
--- /dev/null
+++ b/packages/page-controller/src/mask/cursor.module.css
@@ -0,0 +1,70 @@
+/* AI 光标样式 */
+.cursor {
+	position: absolute;
+	width: var(--cursor-size, 75px);
+	height: var(--cursor-size, 75px);
+	pointer-events: none;
+	z-index: 10000;
+}
+
+.cursorBorder {
+	position: absolute;
+	width: 100%;
+	height: 100%;
+	background: linear-gradient(45deg, rgb(57, 182, 255), rgb(189, 69, 251));
+	mask-image: url(./cursor-border.svg);
+	mask-size: 100% 100%;
+	mask-repeat: no-repeat;
+
+	transform-origin: center;
+	transform: rotate(-135deg) scale(1.2);
+	margin-left: -10px;
+	margin-top: -18px;
+}
+
+.cursorFilling {
+	position: absolute;
+	width: 100%;
+	height: 100%;
+	background: url(./cursor-fill.svg);
+	background-size: 100% 100%;
+	background-repeat: no-repeat;
+
+	transform-origin: center;
+	transform: rotate(-135deg) scale(1.2);
+	margin-left: -10px;
+	margin-top: -18px;
+}
+
+.cursorRipple {
+	position: absolute;
+	width: 100%;
+	height: 100%;
+	pointer-events: none;
+	margin-left: -50%;
+	margin-top: -50%;
+
+	&::after {
+		content: '';
+		opacity: 0;
+		position: absolute;
+		inset: 0;
+		border: 4px solid rgba(57, 182, 255, 1);
+		border-radius: 50%;
+	}
+}
+
+.cursor.clicking .cursorRipple::after {
+	animation: cursor-ripple 300ms ease-out forwards;
+}
+
+@keyframes cursor-ripple {
+	0% {
+		transform: scale(0);
+		opacity: 1;
+	}
+	100% {
+		transform: scale(2);
+		opacity: 0;
+	}
+}
diff --git a/packages/page-controller/src/patches/antd.ts b/packages/page-controller/src/patches/antd.ts
new file mode 100644
index 0000000..e6ebb40
--- /dev/null
+++ b/packages/page-controller/src/patches/antd.ts
@@ -0,0 +1,20 @@
+import type { PageController } from '../PageController'
+
+const clearFunctions = [] as (() => void)[]
+
+/**
+ * antd 的 select 是 div 包 input 的结构，所有信息都在 input 标签上，
+ * 但是 input 不可见，也不会出现在清洗后的树里，因此这里把他提上来
+ */
+function fixAntdSelect() {
+	const selects = [...document.querySelectorAll('input[role="combobox"]')]
+	// for (const select of selects) {}
+}
+
+export function patchAntd(pageController: PageController) {
+	pageController.addEventListener('beforeUpdate', fixAntdSelect)
+	pageController.addEventListener('afterUpdate', () => {
+		for (const fn of clearFunctions) fn()
+		clearFunctions.length = 0
+	})
+}
diff --git a/packages/page-controller/src/patches/react.ts b/packages/page-controller/src/patches/react.ts
new file mode 100644
index 0000000..39b2e6b
--- /dev/null
+++ b/packages/page-controller/src/patches/react.ts
@@ -0,0 +1,16 @@
+import type { PageController } from '../PageController'
+
+// Find common React root elements and add data-page-agent-not-interactive attribute
+export function patchReact(pageController: PageController) {
+	const reactRootElements = document.querySelectorAll(
+		'[data-reactroot], [data-reactid], [data-react-checksum], #root, #app, [id^="root-"], [id^="app-"], #adex-wrapper, #adex-root'
+	)
+
+	for (const element of reactRootElements) {
+		element.setAttribute('data-page-agent-not-interactive', 'true')
+	}
+}
+
+/**
+ * @todo (Heavy, might have false negatives) Interaction detection, if element width/height equals body offsetWidth/Height, consider it root element and non-interactive (React often attaches many events to root elements, causing false positives)
+ */
diff --git a/packages/page-controller/src/utils/index.ts b/packages/page-controller/src/utils/index.ts
new file mode 100644
index 0000000..885357d
--- /dev/null
+++ b/packages/page-controller/src/utils/index.ts
@@ -0,0 +1,80 @@
+// ======= type guards =======
+// @note instanceof fails for elements inside iframes
+
+export function isHTMLElement(el: unknown): el is HTMLElement {
+	// @todo either specify to HTMLElement or allow Element here.
+	return !!el && (el as Node).nodeType === 1
+}
+
+export function isInputElement(el: Element): el is HTMLInputElement {
+	return el?.nodeType === 1 && el.tagName === 'INPUT'
+}
+
+export function isTextAreaElement(el: Element): el is HTMLTextAreaElement {
+	return el?.nodeType === 1 && el.tagName === 'TEXTAREA'
+}
+
+export function isSelectElement(el: Element): el is HTMLSelectElement {
+	return el?.nodeType === 1 && el.tagName === 'SELECT'
+}
+
+export function isAnchorElement(el: Element): el is HTMLAnchorElement {
+	return el?.nodeType === 1 && el.tagName === 'A'
+}
+
+// ======= iframe helpers =======
+
+/** Iframe offset for translating element coordinates to top-frame viewport. */
+export function getIframeOffset(element: HTMLElement): { x: number; y: number } {
+	const frame = element.ownerDocument.defaultView?.frameElement as HTMLElement | null
+	if (!frame) return { x: 0, y: 0 }
+	const rect = frame.getBoundingClientRect()
+	return { x: rect.left, y: rect.top }
+}
+
+/**
+ * Get native value setter from the element's own prototype (iframe-safe).
+ * @note for React
+ */
+export function getNativeValueSetter(element: HTMLInputElement | HTMLTextAreaElement) {
+	// eslint-disable-next-line @typescript-eslint/unbound-method
+	return Object.getOwnPropertyDescriptor(Object.getPrototypeOf(element) as object, 'value')!
+		.set as (v: string) => void
+}
+
+// ======= general utils =======
+
+export async function waitFor(seconds: number): Promise<void> {
+	await new Promise((resolve) => setTimeout(resolve, seconds * 1000))
+}
+
+// ======= mask events =======
+
+/**
+ * Move the visual pointer to a position within an element.
+ * @param x - x coordinate in the element's document viewport
+ * @param y - y coordinate in the element's document viewport
+ */
+export async function movePointerToElement(element: HTMLElement, x: number, y: number) {
+	const offset = getIframeOffset(element)
+
+	window.dispatchEvent(
+		new CustomEvent('PageAgent::MovePointerTo', {
+			detail: { x: x + offset.x, y: y + offset.y },
+		})
+	)
+
+	await waitFor(0.3)
+}
+
+export async function clickPointer() {
+	window.dispatchEvent(new CustomEvent('PageAgent::ClickPointer'))
+}
+
+export async function enablePassThrough() {
+	window.dispatchEvent(new CustomEvent('PageAgent::EnablePassThrough'))
+}
+
+export async function disablePassThrough() {
+	window.dispatchEvent(new CustomEvent('PageAgent::DisablePassThrough'))
+}
diff --git a/packages/page-controller/tsconfig.json b/packages/page-controller/tsconfig.json
new file mode 100644
index 0000000..4344771
--- /dev/null
+++ b/packages/page-controller/tsconfig.json
@@ -0,0 +1,8 @@
+{
+    "extends": "../../tsconfig.base.json",
+    "compilerOptions": {
+        "tsBuildInfoFile": "./node_modules/.tmp/tsconfig.tsbuildinfo"
+    },
+    "include": ["**/*.ts", "**/*.js"],
+    "exclude": ["dist", "node_modules"]
+}
diff --git a/packages/page-controller/vite.config.js b/packages/page-controller/vite.config.js
new file mode 100644
index 0000000..f4fa6d1
--- /dev/null
+++ b/packages/page-controller/vite.config.js
@@ -0,0 +1,52 @@
+// @ts-check
+import chalk from 'chalk'
+import { dirname, resolve } from 'path'
+import dts from 'unplugin-dts/vite'
+import { fileURLToPath } from 'url'
+import { defineConfig } from 'vite'
+import cssInjectedByJsPlugin from 'vite-plugin-css-injected-by-js'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+
+console.log(chalk.cyan(`📦 Building @page-agent/page-controller`))
+
+export default defineConfig({
+	clearScreen: false,
+	plugins: [
+		dts({
+			include: ['src/**/*.ts'],
+			exclude: ['src/**/*.test.ts'],
+			bundleTypes: true,
+			compilerOptions: {
+				composite: true,
+				noEmit: false,
+				emitDeclarationOnly: true,
+				declaration: true,
+			},
+		}),
+		cssInjectedByJsPlugin({ relativeCSSInjection: true }),
+	],
+	publicDir: false,
+	build: {
+		lib: {
+			entry: resolve(__dirname, 'src/PageController.ts'),
+			name: 'PageController',
+			fileName: 'page-controller',
+			formats: ['es'],
+		},
+		outDir: resolve(__dirname, 'dist', 'lib'),
+		rollupOptions: {
+			external: ['@page-agent/*', 'ai-motion'],
+			onwarn: function (message, handler) {
+				if (message.code === 'EVAL') return
+				handler(message)
+			},
+		},
+		minify: false,
+		sourcemap: true,
+		cssCodeSplit: true,
+	},
+	define: {
+		'process.env.NODE_ENV': '"production"',
+	},
+})
diff --git a/packages/page-controller/vitest.config.js b/packages/page-controller/vitest.config.js
new file mode 100644
index 0000000..6877056
--- /dev/null
+++ b/packages/page-controller/vitest.config.js
@@ -0,0 +1,10 @@
+import { defineConfig } from 'vitest/config'
+
+export default defineConfig({
+	test: {
+		name: 'page-controller',
+		environment: 'happy-dom',
+		include: ['src/**/*.test.ts'],
+		silent: 'passed-only',
+	},
+})
diff --git a/packages/ui/package.json b/packages/ui/package.json
new file mode 100644
index 0000000..9e291c3
--- /dev/null
+++ b/packages/ui/package.json
@@ -0,0 +1,48 @@
+{
+    "name": "@page-agent/ui",
+    "version": "1.12.1",
+    "type": "module",
+    "main": "./src/index.ts",
+    "types": "./src/index.ts",
+    "exports": {
+        ".": {
+            "types": "./src/index.ts",
+            "default": "./src/index.ts"
+        }
+    },
+    "publishConfig": {
+        "main": "./dist/lib/page-agent-ui.js",
+        "module": "./dist/lib/page-agent-ui.js",
+        "types": "./dist/lib/index.d.ts",
+        "exports": {
+            ".": {
+                "types": "./dist/lib/index.d.ts",
+                "import": "./dist/lib/page-agent-ui.js",
+                "default": "./dist/lib/page-agent-ui.js"
+            }
+        }
+    },
+    "files": [
+        "dist/"
+    ],
+    "description": "UI components for page-agent - Panel and i18n",
+    "keywords": [
+        "page-agent",
+        "ui",
+        "panel",
+        "i18n"
+    ],
+    "author": "Simon<gaomeng1900>",
+    "license": "MIT",
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/alibaba/page-agent.git",
+        "directory": "packages/ui"
+    },
+    "homepage": "https://alibaba.github.io/page-agent/",
+    "scripts": {
+        "build": "vite build",
+        "prepublishOnly": "node ../../scripts/pre-publish.js",
+        "postpublish": "node ../../scripts/post-publish.js"
+    }
+}
diff --git a/packages/ui/src/env.d.ts b/packages/ui/src/env.d.ts
new file mode 100644
index 0000000..10798a0
--- /dev/null
+++ b/packages/ui/src/env.d.ts
@@ -0,0 +1,6 @@
+/// <reference types="vite/client" />
+
+declare module '*.module.css' {
+	const classes: Record<string, string>
+	export default classes
+}
diff --git a/packages/ui/src/i18n/index.ts b/packages/ui/src/i18n/index.ts
new file mode 100644
index 0000000..2652b32
--- /dev/null
+++ b/packages/ui/src/i18n/index.ts
@@ -0,0 +1,50 @@
+import {
+	type SupportedLanguage,
+	type TranslationKey,
+	type TranslationParams,
+	type TranslationSchema,
+	locales,
+} from './locales'
+
+export class I18n {
+	private language: SupportedLanguage
+	private translations: TranslationSchema
+
+	constructor(language: SupportedLanguage = 'en-US') {
+		this.language = language in locales ? language : 'en-US'
+		this.translations = locales[this.language]
+	}
+
+	// 类型安全的翻译方法
+	t(key: TranslationKey, params?: TranslationParams): string {
+		const value = this.getNestedValue(this.translations, key)
+		if (!value) {
+			console.warn(`Translation key "${key}" not found for language "${this.language}"`)
+			return key
+		}
+
+		if (params) {
+			return this.interpolate(value, params)
+		}
+		return value
+	}
+
+	private getNestedValue(obj: any, path: string): string | undefined {
+		return path.split('.').reduce((current, key) => current?.[key], obj)
+	}
+
+	private interpolate(template: string, params: TranslationParams): string {
+		return template.replace(/\{\{(\w+)\}\}/g, (match, key) => {
+			// Use != null to check for both null and undefined, allow empty strings
+			return params[key] != null ? params[key].toString() : match
+		})
+	}
+
+	getLanguage(): SupportedLanguage {
+		return this.language
+	}
+}
+
+// 导出类型和实例创建函数
+export type { TranslationKey, SupportedLanguage, TranslationParams }
+export { locales }
diff --git a/packages/ui/src/i18n/locales.ts b/packages/ui/src/i18n/locales.ts
new file mode 100644
index 0000000..9250a57
--- /dev/null
+++ b/packages/ui/src/i18n/locales.ts
@@ -0,0 +1,122 @@
+// English translations (base/reference language)
+const enUS = {
+	ui: {
+		panel: {
+			ready: 'Ready',
+			thinking: 'Thinking...',
+			taskInput: 'Enter new task, describe steps in detail, press Enter to submit',
+			userAnswerPrompt: 'Please answer the question above, press Enter to submit',
+			taskTerminated: 'Task terminated',
+			taskCompleted: 'Task completed',
+			userAnswer: 'User answer: {{input}}',
+			question: 'Question: {{question}}',
+			waitingPlaceholder: 'Waiting for task to start...',
+			stop: 'Stop',
+			close: 'Close',
+			expand: 'Expand history',
+			collapse: 'Collapse history',
+			step: 'Step {{number}}',
+		},
+		tools: {
+			clicking: 'Clicking element [{{index}}]...',
+			inputting: 'Inputting text to element [{{index}}]...',
+			selecting: 'Selecting option "{{text}}"...',
+			scrolling: 'Scrolling page...',
+			waiting: 'Waiting {{seconds}} seconds...',
+			askingUser: 'Asking user...',
+			done: 'Task done',
+			clicked: '🖱️ Clicked element [{{index}}]',
+			inputted: '⌨️ Inputted text "{{text}}"',
+			selected: '☑️ Selected option "{{text}}"',
+			scrolled: '🛞 Page scrolled',
+			waited: '⌛️ Wait completed',
+			executing: 'Executing {{toolName}}...',
+			resultSuccess: 'success',
+			resultFailure: 'failed',
+			resultError: 'error',
+		},
+		errors: {
+			elementNotFound: 'No interactive element found at index {{index}}',
+			taskRequired: 'Task description is required',
+			executionFailed: 'Task execution failed',
+			notInputElement: 'Element is not an input or textarea',
+			notSelectElement: 'Element is not a select element',
+			optionNotFound: 'Option "{{text}}" not found',
+		},
+	},
+} as const
+
+// Chinese translations (must match the structure of enUS)
+const zhCN = {
+	ui: {
+		panel: {
+			ready: '准备就绪',
+			thinking: '正在思考...',
+			taskInput: '输入新任务，详细描述步骤，回车提交',
+			userAnswerPrompt: '请回答上面问题，回车提交',
+			taskTerminated: '任务已终止',
+			taskCompleted: '任务结束',
+			userAnswer: '用户回答: {{input}}',
+			question: '询问: {{question}}',
+			waitingPlaceholder: '等待任务开始...',
+			stop: '终止',
+			close: '关闭',
+			expand: '展开历史',
+			collapse: '收起历史',
+			step: '步骤 {{number}}',
+		},
+		tools: {
+			clicking: '正在点击元素 [{{index}}]...',
+			inputting: '正在输入文本到元素 [{{index}}]...',
+			selecting: '正在选择选项 "{{text}}"...',
+			scrolling: '正在滚动页面...',
+			waiting: '等待 {{seconds}} 秒...',
+			askingUser: '正在询问用户...',
+			done: '结束任务',
+			clicked: '🖱️ 已点击元素 [{{index}}]',
+			inputted: '⌨️ 已输入文本 "{{text}}"',
+			selected: '☑️ 已选择选项 "{{text}}"',
+			scrolled: '🛞 页面滚动完成',
+			waited: '⌛️ 等待完成',
+			executing: '正在执行 {{toolName}}...',
+			resultSuccess: '成功',
+			resultFailure: '失败',
+			resultError: '错误',
+		},
+		errors: {
+			elementNotFound: '未找到索引为 {{index}} 的交互元素',
+			taskRequired: '任务描述不能为空',
+			executionFailed: '任务执行失败',
+			notInputElement: '元素不是输入框或文本域',
+			notSelectElement: '元素不是选择框',
+			optionNotFound: '未找到选项 "{{text}}"',
+		},
+	},
+} as const
+
+// Type definitions generated from English base structure (but with string values)
+type DeepStringify<T> = {
+	[K in keyof T]: T[K] extends string ? string : T[K] extends object ? DeepStringify<T[K]> : T[K]
+}
+
+export type TranslationSchema = DeepStringify<typeof enUS>
+
+// Utility type: Extract all nested paths from translation object
+type NestedKeyOf<ObjectType extends object> = {
+	[Key in keyof ObjectType & (string | number)]: ObjectType[Key] extends object
+		? `${Key}` | `${Key}.${NestedKeyOf<ObjectType[Key]>}`
+		: `${Key}`
+}[keyof ObjectType & (string | number)]
+
+// Extract all possible key paths from translation structure
+export type TranslationKey = NestedKeyOf<TranslationSchema>
+
+// Parameterized translation types
+export type TranslationParams = Record<string, string | number>
+
+export const locales = {
+	'en-US': enUS,
+	'zh-CN': zhCN,
+} as const
+
+export type SupportedLanguage = keyof typeof locales
diff --git a/packages/ui/src/index.ts b/packages/ui/src/index.ts
new file mode 100644
index 0000000..debe052
--- /dev/null
+++ b/packages/ui/src/index.ts
@@ -0,0 +1,2 @@
+export { Panel, type PanelConfig } from './panel/Panel'
+export { I18n, type SupportedLanguage, type TranslationKey } from './i18n'
diff --git a/packages/ui/src/panel/Panel.module.css b/packages/ui/src/panel/Panel.module.css
new file mode 100644
index 0000000..92e1c1d
--- /dev/null
+++ b/packages/ui/src/panel/Panel.module.css
@@ -0,0 +1,601 @@
+.wrapper {
+	position: fixed;
+	bottom: 100px;
+	left: 50%;
+	transform: translateX(-50%) translateY(20px);
+	opacity: 0;
+	z-index: 2147483642; /* 比 SimulatorMask 高一层 */
+	box-sizing: border-box;
+
+	overflow: visible;
+
+	* {
+		box-sizing: border-box;
+	}
+
+	--width: 360px;
+	--height: 40px;
+	--border-radius: 12px;
+
+	--side-space: 12px; /* 控制栏两侧的间距 */
+	--history-width: calc(var(--width) - var(--side-space) * 2);
+
+	--color-1: rgb(57, 182, 255);
+	--color-2: rgb(189, 69, 251);
+	--color-3: rgb(255, 87, 51);
+	--color-4: rgb(255, 214, 0);
+
+	width: var(--width);
+	height: var(--height);
+
+	transition: all 0.3s ease-in-out;
+
+	/* 响应式设计 */
+	@media (max-width: 480px) {
+		width: calc(100vw - 40px);
+		--width: calc(100vw - 40px);
+	}
+
+	.background {
+		position: absolute;
+		inset: -2px -8px;
+		border-radius: calc(var(--border-radius) + 4px);
+		filter: blur(16px);
+		overflow: hidden;
+		/* mix-blend-mode: lighten; */
+		/* display: none; */
+
+		&::before {
+			content: '';
+			z-index: -1;
+			pointer-events: none;
+			position: absolute;
+			width: 100%;
+			height: 100%;
+			/* left: -100%; */
+			left: 0;
+			top: 0;
+
+			background-image: linear-gradient(
+				to bottom left,
+				var(--color-1),
+				var(--color-2),
+				var(--color-1)
+			);
+			animation: mask-running 2s linear infinite;
+		}
+		&::after {
+			content: '';
+			z-index: -1;
+			pointer-events: none;
+			position: absolute;
+			width: 100%;
+			height: 100%;
+			left: 0;
+			top: 0;
+
+			background-image: linear-gradient(
+				to bottom left,
+				var(--color-2),
+				var(--color-1),
+				var(--color-2)
+			);
+			animation: mask-running 2s linear infinite;
+			animation-delay: 1s;
+		}
+	}
+}
+
+@keyframes mask-running {
+	from {
+		transform: translateX(-100%);
+	}
+	to {
+		transform: translateX(100%);
+	}
+}
+
+/* 控制栏 */
+.header {
+	display: flex;
+	align-items: center;
+	justify-content: space-between;
+	padding: 8px 12px;
+	user-select: none;
+
+	position: absolute;
+	inset: 0;
+
+	cursor: pointer;
+	flex-shrink: 0; /* 防止 header 被压缩 */
+
+	background: rgba(0, 0, 0, 0.5);
+	backdrop-filter: blur(10px);
+	border-radius: var(--border-radius);
+	background-clip: padding-box;
+
+	box-shadow:
+		0 0 0px 2px rgba(255, 255, 255, 0.4),
+		0 0 5px 1px rgba(255, 255, 255, 0.3);
+
+	.statusSection {
+		display: flex;
+		align-items: center;
+		gap: 8px;
+		flex: 1;
+		min-height: 24px; /* 确保垂直居中 */
+
+		.indicator {
+			width: 6px;
+			height: 6px;
+			border-radius: 50%;
+			background: rgba(255, 255, 255, 0.5);
+			flex-shrink: 0;
+			animation: none; /* 默认无动画 */
+
+			/* 运行状态 - 有动画 */
+			&.thinking {
+				background: rgb(57, 182, 255);
+				animation: pulse 0.8s ease-in-out infinite;
+			}
+
+			&.tool_executing {
+				background: rgb(189, 69, 251);
+				animation: pulse 0.6s ease-in-out infinite;
+			}
+
+			&.retry {
+				background: rgb(255, 214, 0);
+				animation: retryPulse 1s ease-in-out infinite;
+			}
+
+			/* 静止状态 - 无动画 */
+			&.completed,
+			&.input,
+			&.output {
+				background: rgb(34, 197, 94);
+				animation: none;
+			}
+
+			&.error {
+				background: rgb(239, 68, 68);
+				animation: none;
+			}
+		}
+
+		.statusText {
+			color: white;
+			font-size: 12px;
+			line-height: 1;
+			font-weight: 500;
+			transition: all 0.3s ease-in-out;
+			position: relative;
+			overflow: hidden;
+			display: flex;
+			align-items: center;
+			min-height: 24px; /* 确保垂直居中 */
+
+			&.fadeOut {
+				animation: statusTextFadeOut 0.3s ease forwards;
+			}
+
+			&.fadeIn {
+				animation: statusTextFadeIn 0.3s ease forwards;
+			}
+		}
+	}
+
+	.controls {
+		display: flex;
+		align-items: center;
+		gap: 4px;
+
+		.controlButton {
+			width: 24px;
+			height: 24px;
+			border: none;
+			border-radius: 4px;
+			background: rgba(255, 255, 255, 0.1);
+			color: white;
+			cursor: pointer;
+			display: flex;
+			align-items: center;
+			justify-content: center;
+			font-size: 12px;
+			line-height: 1;
+
+			&:hover {
+				background: rgba(255, 255, 255, 0.2);
+			}
+		}
+
+		.stopButton {
+			background: rgba(239, 68, 68, 0.2);
+			color: rgb(255, 41, 41);
+			font-weight: 600;
+
+			&:hover {
+				background: rgba(239, 68, 68, 0.3);
+			}
+		}
+	}
+}
+
+@keyframes statusTextFadeIn {
+	0% {
+		opacity: 0;
+		transform: translateY(5px);
+	}
+	100% {
+		opacity: 1;
+		transform: translateY(0);
+	}
+}
+
+@keyframes statusTextFadeOut {
+	0% {
+		opacity: 1;
+		transform: translateY(0);
+	}
+	100% {
+		opacity: 0;
+		transform: translateY(-5px);
+	}
+}
+
+.historySectionWrapper {
+	position: absolute;
+	width: var(--history-width);
+	bottom: var(--height);
+	left: var(--side-space);
+	z-index: -2;
+
+	padding-top: 0px;
+	visibility: collapse;
+	overflow: hidden;
+
+	transition: all 0.2s;
+
+	background: rgba(2, 0, 20, 0.5);
+	/* background: rgba(186, 186, 186, 0.2); */
+	backdrop-filter: blur(10px);
+
+	text-shadow: 0 0 1px rgba(0, 0, 0, 0.2);
+
+	border-top-left-radius: calc(var(--border-radius) + 4px);
+	border-top-right-radius: calc(var(--border-radius) + 4px);
+
+	/* border: 2px solid rgba(255, 255, 255, 0.8); */
+	border: 2px solid rgba(255, 255, 255, 0.4);
+	box-shadow: 0 4px 16px rgba(0, 0, 0, 0.6);
+
+	/* @media (prefers-color-scheme: dark) {
+		box-shadow:
+			0 8px 32px 0 rgba(0, 0, 0, 0.85),
+			0 2px 12px 0 rgba(57, 182, 255, 0.1);
+	} */
+
+	.expanded & {
+		padding-top: 8px;
+		visibility: visible;
+	}
+
+	.historySection {
+		position: relative;
+		overflow-y: auto;
+		overscroll-behavior: contain;
+		scrollbar-width: none;
+		max-height: 0;
+		padding-inline: 8px;
+
+		transition: max-height 0.2s;
+
+		.expanded & {
+			max-height: min(500px, calc(100vh - 200px - var(--height)));
+		}
+
+		.historyItem {
+			/* backdrop-filter: blur(10px); */
+			padding: 8px 10px;
+			margin-bottom: 6px;
+			background: linear-gradient(135deg, rgba(255, 255, 255, 0.08), rgba(255, 255, 255, 0.03));
+			border-radius: 8px;
+			border-left: 2px solid rgba(57, 182, 255, 0.5);
+			font-size: 12px;
+			color: white;
+			/* color: black; */
+			line-height: 1.3;
+			position: relative;
+			overflow: hidden;
+
+			/* 微妙的内阴影 */
+			box-shadow:
+				inset 0 1px 0 rgba(255, 255, 255, 0.1),
+				0 1px 3px rgba(0, 0, 0, 0.1);
+
+			&::before {
+				content: '';
+				position: absolute;
+				top: 0;
+				left: 0;
+				right: 0;
+				height: 1px;
+				background: linear-gradient(90deg, transparent, rgba(255, 255, 255, 0.2), transparent);
+			}
+
+			&:hover {
+				background: linear-gradient(135deg, rgba(255, 255, 255, 0.12), rgba(255, 255, 255, 0.06));
+				/* transform: translateY(-1px); */
+				box-shadow:
+					inset 0 1px 0 rgba(255, 255, 255, 0.15),
+					0 2px 4px rgba(0, 0, 0, 0.15);
+			}
+
+			&:last-child {
+				margin-bottom: 10px;
+			}
+
+			&.completed,
+			&.input,
+			&.output {
+				border-left-color: rgb(34, 197, 94);
+				background: linear-gradient(135deg, rgba(34, 197, 94, 0.1), rgba(34, 197, 94, 0.05));
+			}
+
+			&.error {
+				border-left-color: rgb(239, 68, 68);
+				background: linear-gradient(135deg, rgba(239, 68, 68, 0.1), rgba(239, 68, 68, 0.05));
+			}
+
+			&.retry {
+				border-left-color: rgb(255, 214, 0);
+				background: linear-gradient(135deg, rgba(255, 214, 0, 0.1), rgba(255, 214, 0, 0.05));
+			}
+
+			&.observation {
+				border-left-color: rgb(147, 51, 234);
+				background: linear-gradient(135deg, rgba(147, 51, 234, 0.1), rgba(147, 51, 234, 0.05));
+			}
+
+			&.question {
+				border-left-color: rgb(255, 159, 67);
+				background: linear-gradient(135deg, rgba(255, 159, 67, 0.15), rgba(255, 159, 67, 0.08));
+			}
+
+			/* 突出显示 done 成功结果 */
+			&.doneSuccess {
+				background: linear-gradient(
+					135deg,
+					rgba(34, 197, 94, 0.25),
+					rgba(34, 197, 94, 0.15),
+					rgba(34, 197, 94, 0.08)
+				);
+				border: none;
+				border-left: 4px solid rgb(34, 197, 94);
+				box-shadow:
+					0 4px 12px rgba(34, 197, 94, 0.3),
+					inset 0 1px 0 rgba(255, 255, 255, 0.2),
+					0 0 20px rgba(34, 197, 94, 0.1);
+				font-weight: 600;
+				color: rgb(220, 252, 231);
+				padding: 10px 12px;
+				margin-bottom: 8px;
+				border-radius: 8px;
+				position: relative;
+				overflow: hidden;
+
+				&::before {
+					background: linear-gradient(90deg, transparent, rgba(34, 197, 94, 0.4), transparent);
+				}
+
+				&::after {
+					content: '';
+					position: absolute;
+					top: 0;
+					left: -100%;
+					width: 100%;
+					height: 100%;
+					background: linear-gradient(90deg, transparent, rgba(255, 255, 255, 0.1), transparent);
+					animation: shimmer 2s ease-in-out infinite;
+				}
+
+				.historyContent {
+					.statusIcon {
+						font-size: 16px;
+						animation: celebrate 0.8s ease-in-out;
+						filter: drop-shadow(0 2px 4px rgba(34, 197, 94, 0.5));
+					}
+				}
+			}
+
+			/* 突出显示 done 失败结果 */
+			&.doneError {
+				background: linear-gradient(
+					135deg,
+					rgba(239, 68, 68, 0.25),
+					rgba(239, 68, 68, 0.15),
+					rgba(239, 68, 68, 0.08)
+				);
+				border: none;
+				border-left: 4px solid rgb(239, 68, 68);
+				box-shadow:
+					0 4px 12px rgba(239, 68, 68, 0.3),
+					inset 0 1px 0 rgba(255, 255, 255, 0.2),
+					0 0 20px rgba(239, 68, 68, 0.1);
+				font-weight: 600;
+				color: rgb(254, 226, 226);
+				padding: 10px 12px;
+				margin-bottom: 8px;
+				border-radius: 8px;
+				position: relative;
+				overflow: hidden;
+
+				&::before {
+					background: linear-gradient(90deg, transparent, rgba(239, 68, 68, 0.4), transparent);
+				}
+
+				.historyContent {
+					.statusIcon {
+						font-size: 16px;
+						filter: drop-shadow(0 2px 4px rgba(239, 68, 68, 0.5));
+					}
+				}
+			}
+
+			.historyContent {
+				display: flex;
+				align-items: flex-start;
+				gap: 8px;
+
+				word-break: break-all;
+				white-space: pre-wrap;
+
+				/* overflow-x: auto; */
+
+				.statusIcon {
+					font-size: 12px;
+					flex-shrink: 0;
+					line-height: 1;
+					transition: all 0.3s ease;
+				}
+
+				.reflectionLines {
+					display: flex;
+					flex-direction: column;
+					gap: 4px;
+				}
+			}
+
+			.historyMeta {
+				font-size: 10px;
+				color: rgba(255, 255, 255, 0.6);
+				/* color: rgb(61, 61, 61); */
+				margin-top: 8px;
+				line-height: 1;
+			}
+		}
+	}
+}
+
+/* 动画关键帧 - 更快的闪烁 */
+@keyframes pulse {
+	0%,
+	100% {
+		opacity: 1;
+		transform: scale(1);
+	}
+	50% {
+		opacity: 0.4;
+		transform: scale(1.3);
+	}
+}
+
+/* 重试动画 - 旋转脉冲 */
+@keyframes retryPulse {
+	0%,
+	100% {
+		opacity: 1;
+		transform: scale(1) rotate(0deg);
+	}
+	25% {
+		opacity: 0.6;
+		transform: scale(1.2) rotate(90deg);
+	}
+	50% {
+		opacity: 0.8;
+		transform: scale(1.1) rotate(180deg);
+	}
+	75% {
+		opacity: 0.6;
+		transform: scale(1.2) rotate(270deg);
+	}
+}
+
+/* 庆祝动画 */
+@keyframes celebrate {
+	0%,
+	100% {
+		transform: scale(1);
+	}
+	25% {
+		transform: scale(1.2) rotate(-5deg);
+	}
+	75% {
+		transform: scale(1.2) rotate(5deg);
+	}
+}
+
+/* done 卡片的光泽效果 */
+@keyframes shimmer {
+	0% {
+		left: -100%;
+	}
+	100% {
+		left: 100%;
+	}
+}
+
+/* 输入区域样式 */
+.inputSectionWrapper {
+	position: absolute;
+	width: var(--history-width);
+	top: var(--height);
+	left: var(--side-space);
+	z-index: -1;
+
+	visibility: visible;
+	overflow: hidden;
+
+	height: 48px;
+
+	transition: all 0.2s;
+
+	background: rgba(186, 186, 186, 0.2);
+	backdrop-filter: blur(10px);
+
+	border-bottom-left-radius: calc(var(--border-radius) + 4px);
+	border-bottom-right-radius: calc(var(--border-radius) + 4px);
+
+	border: 2px solid rgba(255, 255, 255, 0.3);
+	box-shadow: 0 1px 16px rgba(0, 0, 0, 0.4);
+
+	&.hidden {
+		visibility: collapse;
+		height: 0;
+	}
+
+	.inputSection {
+		display: flex;
+		align-items: center;
+		gap: 4px;
+		padding: 8px 8px;
+
+		.taskInput {
+			flex: 1;
+			background: rgba(255, 255, 255, 0.4);
+			border: 1px solid rgba(255, 255, 255, 0.3);
+			border-radius: 10px;
+			padding-inline: 10px;
+			color: rgb(20, 20, 20);
+			font-size: 12px;
+			height: 28px;
+			line-height: 1;
+			outline: none;
+			transition: all 0.2s ease;
+
+			/* text-shadow: 0 0 2px rgba(255, 255, 255, 0.8); */
+
+			/* border-color: rgba(57, 182, 255, 0.3); */
+
+			&::placeholder {
+				color: rgb(53, 53, 53);
+			}
+
+			&:focus {
+				background: rgba(255, 255, 255, 0.8);
+				border-color: rgba(57, 182, 255, 0.6);
+				box-shadow: 0 0 0 2px rgba(57, 182, 255, 0.2);
+			}
+		}
+	}
+}
diff --git a/packages/ui/src/panel/Panel.ts b/packages/ui/src/panel/Panel.ts
new file mode 100644
index 0000000..a65d934
--- /dev/null
+++ b/packages/ui/src/panel/Panel.ts
@@ -0,0 +1,697 @@
+import { I18n, type SupportedLanguage } from '../i18n'
+import { truncate } from '../utils'
+import { createCard, createReflectionLines } from './cards'
+import type { AgentActivity, PanelAgentAdapter } from './types'
+
+import styles from './Panel.module.css'
+
+/**
+ * Panel configuration
+ */
+export interface PanelConfig {
+	language?: SupportedLanguage
+	/**
+	 * Whether to prompt for next task after task completion
+	 * @default true
+	 */
+	promptForNextTask?: boolean
+}
+
+/**
+ * Agent control panel
+ *
+ * Architecture:
+ * - History list: renders directly from agent.history (historical events)
+ * - Header bar: shows activity events (transient state) and agent status
+ *
+ * This separation ensures data consistency - history is the single source of truth
+ * for what has been done, while activity shows what is happening now.
+ */
+export class Panel {
+	#wrapper: HTMLElement
+	#indicator: HTMLElement
+	#statusText: HTMLElement
+	#historySection: HTMLElement
+	#expandButton: HTMLElement
+	#actionButton: HTMLElement
+	#inputSection: HTMLElement
+	#taskInput: HTMLInputElement
+
+	#agent: PanelAgentAdapter
+	#config: PanelConfig
+	#isExpanded = false
+	#i18n: I18n
+	#userAnswerResolver: ((input: string) => void) | null = null
+	#isWaitingForUserAnswer: boolean = false
+	#headerUpdateTimer: ReturnType<typeof setInterval> | null = null
+	#pendingHeaderText: string | null = null
+	#isAnimating = false
+
+	// Event handlers (bound for removal)
+	#onStatusChange = () => this.#handleStatusChange()
+	#onHistoryChange = () => this.#handleHistoryChange()
+	#onActivity = (e: Event) => this.#handleActivity((e as CustomEvent<AgentActivity>).detail)
+	#onAgentDispose = () => this.dispose()
+
+	get wrapper(): HTMLElement {
+		return this.#wrapper
+	}
+
+	/**
+	 * Create a Panel bound to an agent
+	 * @param agent - Agent instance that implements PanelAgentAdapter
+	 * @param config - Optional panel configuration
+	 */
+	constructor(agent: PanelAgentAdapter, config: PanelConfig = {}) {
+		this.#agent = agent
+		this.#config = config
+		this.#i18n = new I18n(config.language ?? 'en-US')
+
+		// Set up askUser callback on agent
+		this.#agent.onAskUser = (question, options) => this.#askUser(question, options?.signal)
+
+		// Create UI elements
+		this.#wrapper = this.#createWrapper()
+		this.#indicator = this.#wrapper.querySelector(`.${styles.indicator}`)!
+		this.#statusText = this.#wrapper.querySelector(`.${styles.statusText}`)!
+		this.#historySection = this.#wrapper.querySelector(`.${styles.historySection}`)!
+		this.#expandButton = this.#wrapper.querySelector(`.${styles.expandButton}`)!
+		this.#actionButton = this.#wrapper.querySelector(`.${styles.stopButton}`)!
+		this.#inputSection = this.#wrapper.querySelector(`.${styles.inputSectionWrapper}`)!
+		this.#taskInput = this.#wrapper.querySelector(`.${styles.taskInput}`)!
+
+		// Listen to agent events
+		this.#agent.addEventListener('statuschange', this.#onStatusChange)
+		this.#agent.addEventListener('historychange', this.#onHistoryChange)
+		this.#agent.addEventListener('activity', this.#onActivity)
+		this.#agent.addEventListener('dispose', this.#onAgentDispose)
+
+		this.#setupEventListeners()
+		this.#startHeaderUpdateLoop()
+
+		this.#showInputArea()
+
+		this.hide() // Start hidden
+	}
+
+	// ========== Agent event handlers ==========
+
+	/** Handle agent status change */
+	#handleStatusChange(): void {
+		const status = this.#agent.status
+
+		// Map agent status to UI indicator. A `completed` run whose result reports
+		// failure shows as error; other statuses map to their own indicator.
+		const failed = status === 'completed' && this.#agent.lastResult?.success === false
+		this.#updateStatusIndicator(failed ? 'error' : status)
+
+		// 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()
+			this.#hideInputArea() // Hide input while running
+		}
+
+		// Handle completion
+		if (status === 'completed' || status === 'error' || status === 'stopped') {
+			if (!this.#isExpanded) {
+				this.#expand()
+			}
+			if (this.#shouldShowInputArea()) {
+				this.#showInputArea()
+			}
+		}
+	}
+
+	/** Handle agent history change - re-render history list from agent.history */
+	#handleHistoryChange(): void {
+		this.#renderHistory()
+	}
+
+	/**
+	 * Handle agent activity - transient state for immediate UI feedback
+	 * Activity events are NOT persisted in history, only used for header bar updates
+	 */
+	#handleActivity(activity: AgentActivity): void {
+		switch (activity.type) {
+			case 'thinking':
+				this.#pendingHeaderText = this.#i18n.t('ui.panel.thinking')
+				this.#updateStatusIndicator('thinking')
+				break
+
+			case 'executing':
+				this.#pendingHeaderText = this.#getToolExecutingText(activity.tool, activity.input)
+				this.#updateStatusIndicator('executing')
+				break
+
+			case 'executed':
+				this.#pendingHeaderText = truncate(activity.output, 50)
+				break
+
+			case 'retrying':
+				this.#pendingHeaderText = `Retrying (${activity.attempt}/${activity.maxAttempts})`
+				this.#updateStatusIndicator('retrying')
+				break
+
+			case 'error':
+				this.#pendingHeaderText = truncate(activity.message, 50)
+				this.#updateStatusIndicator('error')
+				break
+		}
+	}
+
+	/**
+	 * Ask for user input (internal, called by agent via onAskUser).
+	 * Rejects when `signal` aborts (task stopped or disposed), cleaning up the
+	 * question card and pending state so the agent loop can settle.
+	 */
+	#askUser(question: string, signal?: AbortSignal): Promise<string> {
+		return new Promise((resolve, reject) => {
+			// Set `waiting for user answer` state
+			this.#isWaitingForUserAnswer = true
+			this.#userAnswerResolver = resolve
+
+			// Expand history panel
+			if (!this.#isExpanded) {
+				this.#expand()
+			}
+
+			// Add temporary question card so user can see the full question
+			const tempCard = document.createElement('div')
+			tempCard.innerHTML = createCard({
+				icon: '❓',
+				content: `Question: ${question}`,
+				type: 'question',
+			})
+			const cardElement = tempCard.firstElementChild as HTMLElement
+			cardElement.setAttribute('data-temp-card', 'true')
+			this.#historySection.appendChild(cardElement)
+			this.#scrollToBottom()
+
+			this.#showInputArea(this.#i18n.t('ui.panel.userAnswerPrompt'))
+
+			signal?.addEventListener(
+				'abort',
+				() => {
+					this.#removeTempCards()
+					this.#isWaitingForUserAnswer = false
+					this.#userAnswerResolver = null
+					// reason is a DOMException AbortError (abort() takes no args).
+					reject(signal.reason as DOMException)
+				},
+				{ once: true }
+			)
+		})
+	}
+
+	/** Remove temporary question cards (only direct children for safety) */
+	#removeTempCards(): void {
+		Array.from(this.#historySection.children).forEach((child) => {
+			if (child.getAttribute('data-temp-card') === 'true') {
+				child.remove()
+			}
+		})
+	}
+
+	// ========== Public control methods ==========
+
+	show(): void {
+		this.wrapper.style.display = 'block'
+		void this.wrapper.offsetHeight
+		this.wrapper.style.opacity = '1'
+		this.wrapper.style.transform = 'translateX(-50%) translateY(0)'
+	}
+
+	hide(): void {
+		this.wrapper.style.opacity = '0'
+		this.wrapper.style.transform = 'translateX(-50%) translateY(20px)'
+		this.wrapper.style.display = 'none'
+	}
+
+	reset(): void {
+		this.#statusText.textContent = this.#i18n.t('ui.panel.ready')
+		this.#updateStatusIndicator('thinking')
+		this.#renderHistory()
+		this.#collapse()
+		// Reset user input state
+		this.#isWaitingForUserAnswer = false
+		this.#userAnswerResolver = null
+		// Show input area
+		this.#showInputArea()
+	}
+
+	expand(): void {
+		this.#expand()
+	}
+
+	collapse(): void {
+		this.#collapse()
+	}
+
+	/**
+	 * Dispose panel and clean up event listeners
+	 */
+	dispose(): void {
+		// Remove agent event listeners
+		this.#agent.removeEventListener('statuschange', this.#onStatusChange)
+		this.#agent.removeEventListener('historychange', this.#onHistoryChange)
+		this.#agent.removeEventListener('activity', this.#onActivity)
+		this.#agent.removeEventListener('dispose', this.#onAgentDispose)
+
+		// Clean up UI
+		this.#isWaitingForUserAnswer = false
+		this.#stopHeaderUpdateLoop()
+		this.wrapper.remove()
+	}
+
+	// ========== Private methods ==========
+
+	#getToolExecutingText(toolName: string, args: unknown): string {
+		const a = args as Record<string, string | number>
+		switch (toolName) {
+			case 'click_element_by_index':
+				return this.#i18n.t('ui.tools.clicking', { index: a.index })
+			case 'input_text':
+				return this.#i18n.t('ui.tools.inputting', { index: a.index })
+			case 'select_dropdown_option':
+				return this.#i18n.t('ui.tools.selecting', { text: a.text })
+			case 'scroll':
+				return this.#i18n.t('ui.tools.scrolling')
+			case 'wait':
+				return this.#i18n.t('ui.tools.waiting', { seconds: a.seconds })
+			case 'ask_user':
+				return this.#i18n.t('ui.tools.askingUser')
+			case 'done':
+				return this.#i18n.t('ui.tools.done')
+			default:
+				return this.#i18n.t('ui.tools.executing', { toolName })
+		}
+	}
+
+	/**
+	 * Action button handler: stop when running, close (dispose) when idle
+	 */
+	#handleActionButton(): void {
+		if (this.#agent.status === 'running') {
+			this.#agent.stop()
+		} else {
+			this.#agent.dispose()
+		}
+	}
+
+	/**
+	 * Submit task
+	 */
+	#submitTask() {
+		const input = this.#taskInput.value.trim()
+		if (!input) return
+
+		// Hide input area
+		this.#hideInputArea()
+
+		if (this.#isWaitingForUserAnswer) {
+			// Handle user input mode
+			this.#handleUserAnswer(input)
+		} else {
+			// Execute task via agent
+			this.#agent.execute(input)
+		}
+	}
+
+	/**
+	 * Handle user answer
+	 */
+	#handleUserAnswer(input: string): void {
+		this.#removeTempCards()
+
+		// Reset state
+		this.#isWaitingForUserAnswer = false
+
+		// Call resolver to return user input
+		if (this.#userAnswerResolver) {
+			this.#userAnswerResolver(input)
+			this.#userAnswerResolver = null
+		}
+	}
+
+	/**
+	 * Show input area
+	 */
+	#showInputArea(placeholder?: string): void {
+		// Clear input field
+		this.#taskInput.value = ''
+		this.#taskInput.placeholder = placeholder || this.#i18n.t('ui.panel.taskInput')
+		this.#inputSection.classList.remove(styles.hidden)
+		// Focus on input field
+		setTimeout(() => {
+			this.#taskInput.focus()
+		}, 100)
+	}
+
+	/**
+	 * Hide input area
+	 */
+	#hideInputArea(): void {
+		this.#inputSection.classList.add(styles.hidden)
+	}
+
+	/**
+	 * Check if input area should be shown
+	 */
+	#shouldShowInputArea(): boolean {
+		// Always show input area if waiting for user input
+		if (this.#isWaitingForUserAnswer) return true
+
+		const history = this.#agent.history
+		if (history.length === 0) {
+			return true // Initial state
+		}
+
+		const status = this.#agent.status
+		const isTaskEnded = status === 'completed' || status === 'error' || status === 'stopped'
+
+		// Only show input area after task completion if configured to do so
+		if (isTaskEnded) {
+			return this.#config.promptForNextTask ?? true
+		}
+
+		return false
+	}
+
+	#createWrapper(): HTMLElement {
+		const taskInputMaxLength = 1000
+		const wrapper = document.createElement('div')
+		wrapper.id = 'page-agent-runtime_agent-panel'
+		wrapper.className = styles.wrapper
+		wrapper.setAttribute('data-browser-use-ignore', 'true')
+		wrapper.setAttribute('data-page-agent-ignore', 'true')
+
+		wrapper.innerHTML = `
+			<div class="${styles.background}"></div>
+			<div class="${styles.historySectionWrapper}">
+				<div class="${styles.historySection}">
+					<div class="${styles.historyItem}">
+						<div class="${styles.historyContent}">
+							<span class="${styles.statusIcon}">🧠</span>
+							<span>${this.#i18n.t('ui.panel.waitingPlaceholder')}</span>
+						</div>
+					</div>
+				</div>
+			</div>
+			<div class="${styles.header}">
+				<div class="${styles.statusSection}">
+					<div class="${styles.indicator} ${styles.thinking}"></div>
+					<div class="${styles.statusText}">${this.#i18n.t('ui.panel.ready')}</div>
+				</div>
+				<div class="${styles.controls}">
+					<button class="${styles.controlButton} ${styles.expandButton}" title="${this.#i18n.t('ui.panel.expand')}">
+						▼
+					</button>
+					<button class="${styles.controlButton} ${styles.stopButton}" title="${this.#i18n.t('ui.panel.close')}">
+						X
+					</button>
+				</div>
+			</div>
+			<div class="${styles.inputSectionWrapper} ${styles.hidden}">
+				<div class="${styles.inputSection}">
+					<input 
+						type="text" 
+						class="${styles.taskInput}" 
+						maxlength="${taskInputMaxLength}"
+					/>
+				</div>
+			</div>
+		`
+
+		document.body.appendChild(wrapper)
+		return wrapper
+	}
+
+	#setupEventListeners(): void {
+		// Click header area to expand/collapse
+		const header = this.wrapper.querySelector(`.${styles.header}`)!
+		header.addEventListener('click', (e) => {
+			// Don't trigger expand/collapse if clicking on buttons
+			if ((e.target as HTMLElement).closest(`.${styles.controlButton}`)) {
+				return
+			}
+			this.#toggle()
+		})
+
+		// Expand button
+		this.#expandButton.addEventListener('click', (e) => {
+			e.stopPropagation()
+			this.#toggle()
+		})
+
+		// Action button (stop / close)
+		this.#actionButton.addEventListener('click', (e) => {
+			e.stopPropagation()
+			this.#handleActionButton()
+		})
+
+		// Submit on Enter key in input field
+		this.#taskInput.addEventListener('keydown', (e) => {
+			if (e.isComposing) return // Ignore IME composition keys
+			if (e.key === 'Enter') {
+				e.preventDefault()
+				this.#submitTask()
+			}
+		})
+
+		// Prevent input area click event bubbling
+		this.#inputSection.addEventListener('click', (e) => {
+			e.stopPropagation()
+		})
+	}
+
+	#toggle(): void {
+		if (this.#isExpanded) {
+			this.#collapse()
+		} else {
+			this.#expand()
+		}
+	}
+
+	#expand(): void {
+		this.#isExpanded = true
+		this.wrapper.classList.add(styles.expanded)
+		this.#expandButton.textContent = '▲'
+	}
+
+	#collapse(): void {
+		this.#isExpanded = false
+		this.wrapper.classList.remove(styles.expanded)
+		this.#expandButton.textContent = '▼'
+	}
+
+	/**
+	 * Start periodic header update loop
+	 */
+	#startHeaderUpdateLoop(): void {
+		// Check every 450ms (same as total animation duration)
+		this.#headerUpdateTimer = setInterval(() => {
+			this.#checkAndUpdateHeader()
+		}, 450)
+	}
+
+	/**
+	 * Stop periodic header update loop
+	 */
+	#stopHeaderUpdateLoop(): void {
+		if (this.#headerUpdateTimer) {
+			clearInterval(this.#headerUpdateTimer)
+			this.#headerUpdateTimer = null
+		}
+	}
+
+	/**
+	 * Check if header needs update and trigger animation if not currently animating
+	 */
+	#checkAndUpdateHeader(): void {
+		// If no pending text or currently animating, skip
+		if (!this.#pendingHeaderText || this.#isAnimating) {
+			return
+		}
+
+		// If text is already displayed, clear pending and skip
+		if (this.#statusText.textContent === this.#pendingHeaderText) {
+			this.#pendingHeaderText = null
+			return
+		}
+
+		// Start animation
+		const textToShow = this.#pendingHeaderText
+		this.#pendingHeaderText = null
+		this.#animateTextChange(textToShow)
+	}
+
+	/**
+	 * Animate text change with fade out/in effect
+	 */
+	#animateTextChange(newText: string): void {
+		this.#isAnimating = true
+
+		// Fade out current text
+		this.#statusText.classList.add(styles.fadeOut)
+
+		setTimeout(() => {
+			// Update text content
+			this.#statusText.textContent = newText
+
+			// Fade in new text
+			this.#statusText.classList.remove(styles.fadeOut)
+			this.#statusText.classList.add(styles.fadeIn)
+
+			setTimeout(() => {
+				this.#statusText.classList.remove(styles.fadeIn)
+				this.#isAnimating = false
+			}, 300)
+		}, 150) // Half the duration of fade out animation
+	}
+
+	#updateStatusIndicator(
+		type:
+			| 'idle'
+			| 'running'
+			| 'thinking'
+			| 'executing'
+			| 'executed'
+			| 'retrying'
+			| 'completed'
+			| 'error'
+			| 'stopped'
+	): void {
+		// `running` animates like thinking; `idle`/`stopped` use the neutral base.
+		const variant = type === 'running' ? 'thinking' : type
+		this.#indicator.className = styles.indicator
+		if (variant !== 'idle' && variant !== 'stopped') {
+			this.#indicator.classList.add(styles[variant])
+		}
+	}
+
+	#scrollToBottom(): void {
+		// Execute in next event loop to ensure DOM update completion
+		setTimeout(() => {
+			this.#historySection.scrollTop = this.#historySection.scrollHeight
+		}, 0)
+	}
+
+	/**
+	 * Render history directly from agent.history
+	 *
+	 * Renders:
+	 * 1. Task (first item, from agent.task)
+	 * 2. Reflection cards (evaluation, memory, next_goal)
+	 * 3. Tool execution with output
+	 * 4. Observations
+	 */
+	#renderHistory(): void {
+		const items: string[] = []
+
+		// 1. Task card (always first)
+		const task = this.#agent.task
+		if (task) {
+			items.push(this.#createTaskCard(task))
+		}
+
+		// 2. Render each history event
+		const history = this.#agent.history
+		for (const event of history) {
+			items.push(...this.#createHistoryCards(event))
+		}
+
+		this.#historySection.innerHTML = items.join('')
+		this.#scrollToBottom()
+	}
+
+	#createTaskCard(task: string): string {
+		return createCard({ icon: '🎯', content: task, type: 'input' })
+	}
+
+	/** Create cards for a history event */
+	#createHistoryCards(event: PanelAgentAdapter['history'][number]): string[] {
+		const cards: string[] = []
+		const meta =
+			event.type === 'step' && event.stepIndex !== undefined
+				? this.#i18n.t('ui.panel.step', {
+						number: (event.stepIndex + 1).toString(),
+					})
+				: undefined
+
+		if (event.type === 'step') {
+			// Reflection card
+			if (event.reflection) {
+				const lines = createReflectionLines(event.reflection)
+				if (lines.length > 0) {
+					cards.push(createCard({ icon: '🧠', content: lines, meta }))
+				}
+			}
+
+			// Action card
+			const action = event.action
+			if (action) {
+				cards.push(...this.#createActionCards(action, meta))
+			}
+		} else if (event.type === 'observation') {
+			cards.push(
+				createCard({ icon: '👁️', content: event.content || '', meta, type: 'observation' })
+			)
+		} else if (event.type === 'user_takeover') {
+			cards.push(createCard({ icon: '👤', content: 'User takeover', meta, type: 'input' }))
+		} else if (event.type === 'retry') {
+			const retryInfo = `${event.message || 'Retrying'} (${event.attempt}/${event.maxAttempts})`
+			cards.push(createCard({ icon: '🔄', content: retryInfo, meta, type: 'observation' }))
+		} else if (event.type === 'error') {
+			cards.push(
+				createCard({ icon: '❌', content: event.message || 'Error', meta, type: 'observation' })
+			)
+		}
+
+		return cards
+	}
+
+	/** Create cards for an action */
+	#createActionCards(
+		action: { name: string; input: unknown; output: string },
+		meta?: string
+	): string[] {
+		const cards: string[] = []
+
+		if (action.name === 'done') {
+			const input = action.input as { text?: string }
+			const text = input.text || action.output || ''
+			if (text) {
+				cards.push(createCard({ icon: '🤖', content: text, meta, type: 'output' }))
+			}
+		} else if (action.name === 'ask_user') {
+			const input = action.input as { question?: string }
+			const answer = action.output.replace(/^User answered:\s*/i, '')
+			cards.push(
+				createCard({
+					icon: '❓',
+					content: `Question: ${input.question || ''}`,
+					meta,
+					type: 'question',
+				})
+			)
+			cards.push(createCard({ icon: '💬', content: `Answer: ${answer}`, meta, type: 'input' }))
+		} else {
+			const toolText = this.#getToolExecutingText(action.name, action.input)
+			cards.push(createCard({ icon: '🔨', content: toolText, meta }))
+			if (action.output?.length > 0) {
+				cards.push(createCard({ icon: '🔨', content: action.output, meta, type: 'output' }))
+			}
+		}
+
+		return cards
+	}
+}
diff --git a/packages/ui/src/panel/cards.ts b/packages/ui/src/panel/cards.ts
new file mode 100644
index 0000000..0df52c2
--- /dev/null
+++ b/packages/ui/src/panel/cards.ts
@@ -0,0 +1,52 @@
+/**
+ * Card HTML generation utilities for Panel
+ */
+import { escapeHtml } from '../utils'
+
+import styles from './Panel.module.css'
+
+type CardType = 'default' | 'input' | 'output' | 'question' | 'observation'
+
+interface CardOptions {
+	icon: string
+	content: string | string[]
+	meta?: string
+	type?: CardType
+}
+
+/** Create a single history card */
+export function createCard({ icon, content, meta, type }: CardOptions): string {
+	const typeClass = type ? styles[type] : ''
+	const contentHtml = Array.isArray(content)
+		? `<div class="${styles.reflectionLines}">${content.map((line) => `<span>${escapeHtml(line)}</span>`).join('')}</div>`
+		: `<span>${escapeHtml(content)}</span>`
+
+	return `
+		<div class="${styles.historyItem} ${typeClass}">
+			<div class="${styles.historyContent}">
+				<span class="${styles.statusIcon}">${icon}</span>
+				${contentHtml}
+			</div>
+			${meta ? `<div class="${styles.historyMeta}">${meta}</div>` : ''}
+		</div>
+	`
+}
+
+/** Create reflection lines from reflection object */
+export function createReflectionLines(reflection: {
+	evaluation_previous_goal?: string
+	memory?: string
+	next_goal?: string
+}): string[] {
+	const lines: string[] = []
+	if (reflection.evaluation_previous_goal) {
+		lines.push(`🔍 ${reflection.evaluation_previous_goal}`)
+	}
+	if (reflection.memory) {
+		lines.push(`💾 ${reflection.memory}`)
+	}
+	if (reflection.next_goal) {
+		lines.push(`🎯 ${reflection.next_goal}`)
+	}
+	return lines
+}
diff --git a/packages/ui/src/panel/types.ts b/packages/ui/src/panel/types.ts
new file mode 100644
index 0000000..d3ac663
--- /dev/null
+++ b/packages/ui/src/panel/types.ts
@@ -0,0 +1,81 @@
+/**
+ * Agent activity - transient state for immediate UI feedback.
+ *
+ * Unlike historical events (which are persisted), activities are ephemeral
+ * and represent "what the agent is doing right now". UI components should
+ * listen to 'activity' events to show real-time feedback.
+ *
+ * Note: There is no 'idle' activity - absence of activity events means idle.
+ *
+ * Events dispatched: CustomEvent<AgentActivity>
+ */
+export 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 }
+
+/**
+ * Minimal interface that Panel expects from an agent.
+ * Panel does not depend on PageAgent directly - it only requires this interface.
+ * This enables decoupling and allows any agent implementation to work with Panel.
+ *
+ * Events:
+ * - 'statuschange': Agent status changed
+ * - 'historychange': Historical events updated (persisted)
+ * - 'activity': Transient activity for immediate UI feedback (thinking/executing/etc)
+ * - 'dispose': Agent is being disposed
+ */
+export interface PanelAgentAdapter extends EventTarget {
+	/** Current agent status */
+	readonly status: 'idle' | 'running' | 'completed' | 'error' | 'stopped'
+
+	/** Result of the most recent run, or `null` before the first run completes */
+	readonly lastResult: { success: boolean } | null
+
+	/** History of agent events */
+	readonly history: readonly {
+		type: 'step' | 'observation' | 'user_takeover' | 'retry' | 'error'
+		stepIndex?: number
+		/** For 'step' type */
+		reflection?: {
+			evaluation_previous_goal?: string
+			memory?: string
+			next_goal?: string
+		}
+		/** For 'step' type */
+		action?: {
+			name: string
+			input: unknown
+			output: string
+		}
+		/** For 'observation' type */
+		content?: string
+		/** For 'retry' type */
+		attempt?: number
+		maxAttempts?: number
+		/** For 'retry' and 'error' types */
+		message?: string
+	}[]
+
+	/** Current task being executed */
+	readonly task: string
+
+	/**
+	 * Called when the agent needs to ask the user questions.
+	 * If unset, the `ask_user` tool will be disabled.
+	 * Panel will set this to handle user questions via its UI.
+	 * The optional `signal` aborts when the task is stopped or disposed.
+	 */
+	onAskUser?: (question: string, options?: { signal: AbortSignal }) => Promise<string>
+
+	/** Execute a task */
+	execute(task: string): Promise<unknown>
+
+	/** Stop the current task (agent remains reusable) */
+	stop(): Promise<void>
+
+	/** Dispose the agent (terminal, cannot be reused) */
+	dispose(): void
+}
diff --git a/packages/ui/src/utils.ts b/packages/ui/src/utils.ts
new file mode 100644
index 0000000..744d198
--- /dev/null
+++ b/packages/ui/src/utils.ts
@@ -0,0 +1,18 @@
+export function truncate(text: string, maxLength: number): string {
+	if (text.length > maxLength) {
+		return text.substring(0, maxLength) + '...'
+	}
+	return text
+}
+
+/**
+ * Escape HTML special characters to prevent XSS and rendering issues
+ */
+export function escapeHtml(text: string): string {
+	return text
+		.replace(/&/g, '&')
+		.replace(/</g, '<')
+		.replace(/>/g, '>')
+		.replace(/"/g, '"')
+		.replace(/'/g, ''')
+}
diff --git a/packages/ui/tsconfig.json b/packages/ui/tsconfig.json
new file mode 100644
index 0000000..4344771
--- /dev/null
+++ b/packages/ui/tsconfig.json
@@ -0,0 +1,8 @@
+{
+    "extends": "../../tsconfig.base.json",
+    "compilerOptions": {
+        "tsBuildInfoFile": "./node_modules/.tmp/tsconfig.tsbuildinfo"
+    },
+    "include": ["**/*.ts", "**/*.js"],
+    "exclude": ["dist", "node_modules"]
+}
diff --git a/packages/ui/vite.config.js b/packages/ui/vite.config.js
new file mode 100644
index 0000000..7edc3d8
--- /dev/null
+++ b/packages/ui/vite.config.js
@@ -0,0 +1,48 @@
+// @ts-check
+import chalk from 'chalk'
+import { dirname, resolve } from 'path'
+import dts from 'unplugin-dts/vite'
+import { fileURLToPath } from 'url'
+import { defineConfig } from 'vite'
+import cssInjectedByJsPlugin from 'vite-plugin-css-injected-by-js'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+
+console.log(chalk.cyan(`📦 Building @page-agent/ui`))
+
+export default defineConfig({
+	clearScreen: false,
+	plugins: [
+		dts({
+			include: ['src/**/*.ts'],
+			exclude: ['src/**/*.test.ts'],
+			bundleTypes: true,
+			compilerOptions: {
+				composite: true,
+				noEmit: false,
+				emitDeclarationOnly: true,
+				declaration: true,
+			},
+		}),
+		cssInjectedByJsPlugin({ relativeCSSInjection: true }),
+	],
+	publicDir: false,
+	build: {
+		lib: {
+			entry: resolve(__dirname, 'src/index.ts'),
+			name: 'PageAgentUI',
+			fileName: 'page-agent-ui',
+			formats: ['es'],
+		},
+		outDir: resolve(__dirname, 'dist', 'lib'),
+		rollupOptions: {
+			external: [],
+		},
+		minify: false,
+		sourcemap: true,
+		cssCodeSplit: true,
+	},
+	define: {
+		'process.env.NODE_ENV': '"production"',
+	},
+})
diff --git a/packages/website/AGENTS.md b/packages/website/AGENTS.md
new file mode 100644
index 0000000..16e98db
--- /dev/null
+++ b/packages/website/AGENTS.md
@@ -0,0 +1,127 @@
+# Website Package - Instructions for Coding Assistants
+
+## Tech Stack
+
+- **React** with TypeScript
+- **Vite** for dev server and build
+- **Tailwind CSS** for styling
+- **shadcn/ui** (new-york style) for UI components — **do NOT hand-edit `src/components/ui/` files**
+- **Magic UI** for animations and effects
+- **wouter** with browser routing (`base: "/page-agent"`)
+- **lucide-react** for icons
+
+## Component Guidelines
+
+### Use shadcn/ui Components First
+
+**ALWAYS prefer shadcn/ui components over custom implementations.**
+
+Before creating any UI component, check if shadcn already provides it:
+
+```bash
+# IMPORTANT: Run from packages/website/, NOT from repo root
+cd packages/website
+
+# Add a new shadcn component
+npx shadcn@latest add <component-name>
+
+# Add a Magic UI component
+npx shadcn@latest add "@magicui/<component-name>"
+```
+
+Available shadcn components: https://ui.shadcn.com/docs/components
+Available Magic UI components: https://magicui.design/docs/components
+
+### Current UI Components
+
+Located in `src/components/ui/`:
+
+**From shadcn/ui:**
+
+- `alert`, `badge`, `button`, `separator`, `sonner`, `switch`, `tooltip`
+
+**From Magic UI:**
+
+- `animated-gradient-text`, `animated-shiny-text`, `aurora-text`
+- `hyper-text`, `magic-card`, `neon-gradient-card`, `particles`
+- `sparkles-text`, `text-animate`, `typing-animation`
+
+**Custom:**
+
+- `highlighter`, `kbd`, `spinner`
+
+### Styling Rules
+
+1. **Prefer Tailwind classes** over custom CSS
+2. Support dark mode via `dark:` classes
+3. Use CSS variables from `src/index.css` for theme colors
+
+## Project Structure
+
+```
+src/
+├── pages/
+│   ├── home/
+│   │   ├── index.tsx  # Homepage
+│   │   └── ...Section.tsx
+│   └── docs/
+│       ├── index.tsx    # Docs route switch
+│       ├── Layout.tsx   # Sidebar navigation
+│       └── [section]/[topic]/page.tsx
+├── 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           # 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 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`
+5. Keep `<slug>` consistent across the folder name, import path, route path, sidebar link, and any related cross-links. If the public route changes, rename the folder too.
+
+## Configuration Files
+
+| File              | Purpose                 |
+| ----------------- | ----------------------- |
+| `components.json` | shadcn/ui configuration |
+| `vite.config.js`  | Vite build + SPA routes |
+| `tsconfig.json`   | TypeScript config       |
+
+## Commands
+
+```bash
+npm start            # Dev server (from root)
+npm run build:website    # Build website (from root)
+```
diff --git a/packages/website/components.json b/packages/website/components.json
new file mode 100644
index 0000000..423eaa0
--- /dev/null
+++ b/packages/website/components.json
@@ -0,0 +1,24 @@
+{
+    "$schema": "https://ui.shadcn.com/schema.json",
+    "style": "new-york",
+    "rsc": false,
+    "tsx": true,
+    "tailwind": {
+        "config": "",
+        "css": "src/index.css",
+        "baseColor": "neutral",
+        "cssVariables": true,
+        "prefix": ""
+    },
+    "iconLibrary": "lucide",
+    "aliases": {
+        "components": "@/components",
+        "utils": "@/lib/utils",
+        "ui": "@/components/ui",
+        "lib": "@/lib",
+        "hooks": "@/hooks"
+    },
+    "registries": {
+        "@magicui": "https://magicui.design/r/{name}.json"
+    }
+}
diff --git a/packages/website/index.html b/packages/website/index.html
new file mode 100644
index 0000000..e8e5cd1
--- /dev/null
+++ b/packages/website/index.html
@@ -0,0 +1,97 @@
+<!doctype html>
+<html lang="zh-CN">
+	<head>
+		<meta charset="UTF-8" />
+		<link
+			rel="icon"
+			type="image/webp"
+			href="https://page-agent.github.io/assets/brand/page-agent-color-64.webp"
+		/>
+		<meta name="viewport" content="width=device-width, initial-scale=1.0" />
+		<title>PageAgent - The GUI Agent Living in Your Webpage</title>
+		<meta
+			name="description"
+			content="PageAgent.js: Intelligent GUI Agent for any website. Modern web AI automation with minimal integration."
+		/>
+		<meta
+			name="keywords"
+			content="PageAgent, AI Agent, GUI Agent, Web Automation, GUI Automation, Frontend, CDN, JavaScript, React, Vite, LLM"
+		/>
+		<meta
+			property="og:image"
+			content="https://page-agent.github.io/assets/brand/page-agent-color-512.webp"
+		/>
+		<meta property="og:url" content="https://alibaba.github.io/page-agent" />
+		<meta property="og:type" content="website" />
+		<meta name="theme-color" content="#58c0fc" />
+		<meta name="color-scheme" content="light dark" />
+		<meta name="author" content="PageAgent.js Team" />
+		<meta property="og:title" content="PageAgent.js - AI-powered GUI Agent" />
+		<meta property="og:description" content="The GUI Agent living in your website." />
+		<meta property="og:type" content="website" />
+		<meta property="og:locale" content="en_US" />
+		<meta property="og:locale:alternate" content="zh_CN" />
+
+		
+		
+		<script async src="https://www.googletagmanager.com/gtag/js?id=G-HCGRJTN3HM"></script>
+		<script>
+			window.dataLayer = window.dataLayer || []
+			function gtag() {
+				dataLayer.push(arguments)
+			}
+			gtag('js', new Date())
+
+			gtag('config', 'G-HCGRJTN3HM')
+		</script>
+		
+	</head>
+	<body>
+		<div id="root">
+			<div 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: 0.6;
+						}
+						50% {
+							opacity: 0.3;
+						}
+					}
+				</style>
+			</div>
+		</div>
+		<script type="module" src="./src/main.tsx"></script>
+		<script>
+			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)
+		</script>
+	</body>
+</html>
diff --git a/packages/website/package.json b/packages/website/package.json
new file mode 100644
index 0000000..2675db5
--- /dev/null
+++ b/packages/website/package.json
@@ -0,0 +1,34 @@
+{
+    "name": "@page-agent/website",
+    "private": true,
+    "version": "1.12.1",
+    "type": "module",
+    "scripts": {
+        "dev": "vite --host 0.0.0.0",
+        "build:website": "vite build",
+        "preview": "vite preview"
+    },
+    "devDependencies": {
+        "@radix-ui/react-icons": "^1.3.2",
+        "@radix-ui/react-separator": "^1.1.11",
+        "@radix-ui/react-slot": "^1.3.0",
+        "@radix-ui/react-switch": "^1.3.3",
+        "@radix-ui/react-tooltip": "^1.2.12",
+        "@types/react": "^19.2.17",
+        "@types/react-dom": "^19.2.3",
+        "class-variance-authority": "^0.7.1",
+        "clsx": "^2.1.1",
+        "lucide-react": "^1.24.0",
+        "motion": "^12.42.2",
+        "next-themes": "^0.4.6",
+        "react": "^19.2.7",
+        "react-dom": "^19.2.7",
+        "rough-notation": "^0.5.1",
+        "simple-icons": "^16.25.0",
+        "sonner": "^2.0.7",
+        "tailwind-merge": "^3.6.0",
+        "tailwindcss": "^4.3.2",
+        "tw-animate-css": "^1.4.0",
+        "wouter": "^3.10.0"
+    }
+}
diff --git a/packages/website/public/robots.txt b/packages/website/public/robots.txt
new file mode 100644
index 0000000..fa1ce2b
--- /dev/null
+++ b/packages/website/public/robots.txt
@@ -0,0 +1,4 @@
+User-agent: *
+Allow: /
+
+Sitemap: https://alibaba.github.io/page-agent/sitemap.xml
diff --git a/packages/website/src/components/APIReference.tsx b/packages/website/src/components/APIReference.tsx
new file mode 100644
index 0000000..6b6f651
--- /dev/null
+++ b/packages/website/src/components/APIReference.tsx
@@ -0,0 +1,175 @@
+/**
+ * API Reference component for displaying TypeScript interface definitions
+ *
+ * Provides a beautiful, readable table for documenting API interfaces
+ */
+import * as React from 'react'
+
+import { Badge } from '@/components/ui/badge'
+import { cn } from '@/lib/utils'
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export interface PropDefinition {
+	/** Property name */
+	name: string
+	/** TypeScript type (can include generics, unions, etc.) */
+	type: string
+	/** Whether the property is required */
+	required?: boolean
+	/** Default value if any */
+	defaultValue?: string
+	/** Description of the property */
+	description: React.ReactNode
+	/** Mark as experimental/deprecated */
+	status?: 'experimental' | 'deprecated'
+}
+
+export interface APIReferenceProps {
+	/** Title for the API section */
+	title?: string
+	/** Optional description */
+	description?: React.ReactNode
+	/** Property definitions */
+	properties: PropDefinition[]
+	/** Display variant: 'properties' for fields, 'methods' for methods */
+	variant?: 'properties' | 'methods'
+	/** Additional CSS classes */
+	className?: string
+}
+
+// ============================================================================
+// Component
+// ============================================================================
+
+export function APIReference({
+	title,
+	description,
+	properties,
+	variant = 'properties',
+	className,
+}: APIReferenceProps) {
+	const isMethodsVariant = variant === 'methods'
+	return (
+		<div className={cn('my-6', className)}>
+			{title && (
+				<h3 className="text-lg font-semibold text-gray-900 dark:text-gray-100 mb-2">{title}</h3>
+			)}
+			{description && (
+				<p className="text-sm text-gray-600 dark:text-gray-400 mb-4">{description}</p>
+			)}
+
+			<div className="overflow-hidden rounded-lg border border-gray-200 dark:border-gray-700">
+				<table className="w-full text-sm">
+					<thead>
+						<tr className="bg-gray-50 dark:bg-gray-800/50">
+							<th className="px-4 py-3 text-left font-medium text-gray-600 dark:text-gray-300">
+								{isMethodsVariant ? 'Method' : 'Property'}
+							</th>
+							<th className="px-4 py-3 text-left font-medium text-gray-600 dark:text-gray-300">
+								{isMethodsVariant ? 'Return Type' : 'Type'}
+							</th>
+							<th className="px-4 py-3 text-left font-medium text-gray-600 dark:text-gray-300 hidden md:table-cell">
+								Default
+							</th>
+							<th className="px-4 py-3 text-left font-medium text-gray-600 dark:text-gray-300">
+								Description
+							</th>
+						</tr>
+					</thead>
+					<tbody className="divide-y divide-gray-100 dark:divide-gray-800">
+						{properties.map((prop) => (
+							<PropRow key={prop.name} {...prop} />
+						))}
+					</tbody>
+				</table>
+			</div>
+		</div>
+	)
+}
+
+function PropRow({ name, type, required, defaultValue, description, status }: PropDefinition) {
+	return (
+		<tr className="bg-white dark:bg-gray-900 hover:bg-gray-50 dark:hover:bg-gray-800/50 transition-colors">
+			{/* Property name */}
+			<td className="px-4 py-3 align-top">
+				<div className="flex items-center gap-2 flex-wrap">
+					<code className="font-mono text-sm font-medium text-indigo-600 dark:text-indigo-400">
+						{name}
+					</code>
+					{required && (
+						<Badge
+							variant="outline"
+							className="text-[10px] px-1.5 py-0 border-red-300 text-red-600 dark:border-red-800 dark:text-red-400"
+						>
+							required
+						</Badge>
+					)}
+					{status === 'experimental' && (
+						<Badge
+							variant="outline"
+							className="text-[10px] px-1.5 py-0 border-amber-300 text-amber-600 dark:border-amber-800 dark:text-amber-400"
+						>
+							experimental
+						</Badge>
+					)}
+					{status === 'deprecated' && (
+						<Badge
+							variant="outline"
+							className="text-[10px] px-1.5 py-0 border-gray-300 text-gray-500 dark:border-gray-700 dark:text-gray-500 line-through"
+						>
+							deprecated
+						</Badge>
+					)}
+				</div>
+			</td>
+
+			{/* Type */}
+			<td className="px-4 py-3 align-top">
+				<code className="font-mono text-xs text-gray-700 dark:text-gray-300 bg-gray-100 dark:bg-gray-800 px-1.5 py-0.5 rounded wrap-break-word">
+					{type}
+				</code>
+			</td>
+
+			{/* Default value */}
+			<td className="px-4 py-3 align-top hidden md:table-cell">
+				{defaultValue ? (
+					<code className="font-mono text-xs text-gray-600 dark:text-gray-400">{defaultValue}</code>
+				) : (
+					<span className="text-gray-400 dark:text-gray-600">-</span>
+				)}
+			</td>
+
+			{/* Description */}
+			<td className="px-4 py-3 align-top text-gray-600 dark:text-gray-400">{description}</td>
+		</tr>
+	)
+}
+
+// ============================================================================
+// Utility Components
+// ============================================================================
+
+/** Code inline span for type references in descriptions */
+export function TypeRef({ children }: { children: React.ReactNode }) {
+	return (
+		<code className="font-mono text-xs text-indigo-600 dark:text-indigo-400 bg-indigo-50 dark:bg-indigo-950/50 px-1 py-0.5 rounded">
+			{children}
+		</code>
+	)
+}
+
+/** Section divider for grouping related APIs */
+export function APIDivider({ title }: { title: string }) {
+	return (
+		<div className="flex items-center gap-4 my-8">
+			<div className="h-px flex-1 bg-gradient-to-r from-transparent via-gray-200 dark:via-gray-700 to-transparent" />
+			<span className="text-xs font-medium uppercase tracking-wider text-gray-500 dark:text-gray-400">
+				{title}
+			</span>
+			<div className="h-px flex-1 bg-gradient-to-r from-transparent via-gray-200 dark:via-gray-700 to-transparent" />
+		</div>
+	)
+}
diff --git a/packages/website/src/components/BetaNotice.tsx b/packages/website/src/components/BetaNotice.tsx
new file mode 100644
index 0000000..53087b5
--- /dev/null
+++ b/packages/website/src/components/BetaNotice.tsx
@@ -0,0 +1,25 @@
+import { useLanguage } from '@/i18n/context'
+
+export default function BetaNotice() {
+	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">
+			<div className="flex items-start">
+				<div className="shrink-0">
+					<span className="text-xl">🚧</span>
+				</div>
+				<div className="ml-3">
+					<h3 className="text-sm font-medium text-orange-800 dark:text-orange-200 mb-1">
+						{isZh ? 'Beta 阶段' : 'Beta Stage'}
+					</h3>
+					<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>
+	)
+}
diff --git a/packages/website/src/components/CodeEditor.tsx b/packages/website/src/components/CodeEditor.tsx
new file mode 100644
index 0000000..c16ebd0
--- /dev/null
+++ b/packages/website/src/components/CodeEditor.tsx
@@ -0,0 +1,129 @@
+/**
+ * 代码编辑器组件，模拟现代代码编辑器的外观
+ */
+import React from 'react'
+
+import HighlightSyntax from './HighlightSyntax'
+
+interface CodeEditorProps {
+	code: string
+	language?: string
+	title?: string
+	showLineNumbers?: boolean
+	showHeader?: boolean
+	showFooter?: boolean
+	className?: string
+}
+
+const CodeEditor: React.FC<CodeEditorProps> = ({
+	code,
+	language = 'javascript',
+	title,
+	showLineNumbers = false,
+	showHeader = false,
+	showFooter = false,
+	className = '',
+}) => {
+	const lines = code.split('\n')
+
+	// 使用 Tailwind 的 dark: 前缀实现自动主题切换
+	const containerClasses =
+		'bg-linear-to-br from-gray-50 to-gray-100 dark:from-gray-900 dark:to-gray-800 border-gray-300 dark:border-gray-700'
+	const headerClasses = 'bg-gray-100 dark:bg-gray-800 border-gray-300 dark:border-gray-700'
+	const headerTextClasses = 'text-gray-700 dark:text-gray-300'
+	const languageTextClasses = 'text-gray-600 dark:text-gray-400'
+	const lineNumbersClasses =
+		'bg-gray-100 dark:bg-gray-800 border-gray-300 dark:border-gray-700 text-gray-600 dark:text-gray-500'
+	const codeAreaClasses = 'bg-white dark:bg-gray-900'
+	const footerClasses =
+		'bg-gray-100 dark:bg-gray-800 border-gray-300 dark:border-gray-700 text-gray-600 dark:text-gray-400'
+	const copyButtonClasses =
+		'bg-gray-200 hover:bg-gray-300 dark:bg-gray-700 dark:hover:bg-gray-600 text-gray-600 hover:text-gray-800 dark:text-gray-300 dark:hover:text-white'
+
+	return (
+		<div
+			className={`group relative ${containerClasses} rounded-xl border shadow-2xl my-4 overflow-hidden ${className}`}
+		>
+			{/* 编辑器顶部栏 */}
+			{showHeader && (
+				<div className={`flex items-center justify-between px-4 py-3 ${headerClasses} border-b`}>
+					<div className="flex items-center space-x-3">
+						{/* 窗口控制按钮 */}
+						<div className="flex space-x-2">
+							<div className="w-3 h-3 bg-red-500 rounded-full"></div>
+							<div className="w-3 h-3 bg-yellow-500 rounded-full"></div>
+							<div className="w-3 h-3 bg-green-500 rounded-full"></div>
+						</div>
+						{title && (
+							<span className={`text-sm ${headerTextClasses} font-medium ml-2`}>{title}</span>
+						)}
+					</div>
+					<div className="flex items-center space-x-2">
+						<span className={`text-xs ${languageTextClasses} uppercase tracking-wide`}>
+							{language}
+						</span>
+						<div className="w-2 h-2 bg-green-400 rounded-full animate-pulse"></div>
+					</div>
+				</div>
+			)}
+
+			{/* 代码内容区域 */}
+			<div className="relative">
+				<div className="flex">
+					{/* 行号 */}
+					{showLineNumbers && (
+						<div className={`shrink-0 px-4 py-4 ${lineNumbersClasses} border-r select-none`}>
+							<div className="text-xs font-mono leading-6">
+								{lines.map((line, lineIdx) => {
+									const lineNum = lineIdx + 1
+									return (
+										<div key={`${lineNum}-${line.substring(0, 20)}`} className="text-right">
+											{lineNum}
+										</div>
+									)
+								})}
+							</div>
+						</div>
+					)}
+
+					{/* 代码内容 */}
+					<div className={`flex-1 px-4 py-4 ${codeAreaClasses} overflow-x-auto`}>
+						<div className="text-sm font-mono leading-6">
+							<HighlightSyntax code={code} />
+						</div>
+					</div>
+				</div>
+
+				{/* 复制按钮 */}
+				<button
+					onClick={() => {
+						navigator.clipboard.writeText(code).catch(console.error)
+					}}
+					className={`absolute top-3 right-3 p-2 ${copyButtonClasses} rounded-lg transition-all duration-200 opacity-0 group-hover:opacity-100`}
+					title="复制代码"
+				>
+					<svg className="w-4 h-4" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+						<path
+							strokeLinecap="round"
+							strokeLinejoin="round"
+							strokeWidth={2}
+							d="M8 16H6a2 2 0 01-2-2V6a2 2 0 012-2h8a2 2 0 012 2v2m-6 12h8a2 2 0 002-2v-8a2 2 0 00-2-2h-8a2 2 0 00-2 2v8a2 2 0 002 2z"
+						/>
+					</svg>
+				</button>
+			</div>
+
+			{/* 底部状态栏 */}
+			{showFooter && (
+				<div className={`px-4 py-2 ${footerClasses} border-t`}>
+					<div className="flex items-center justify-between text-xs">
+						<span>{lines.length} lines</span>
+						<span>UTF-8</span>
+					</div>
+				</div>
+			)}
+		</div>
+	)
+}
+
+export default CodeEditor
diff --git a/packages/website/src/components/Footer.tsx b/packages/website/src/components/Footer.tsx
new file mode 100644
index 0000000..81869f2
--- /dev/null
+++ b/packages/website/src/components/Footer.tsx
@@ -0,0 +1,77 @@
+import { siGithub, siX } from 'simple-icons'
+
+import { useLanguage } from '@/i18n/context'
+
+export default function Footer() {
+	const { isZh } = useLanguage()
+
+	return (
+		<footer
+			className="bg-gray-50 dark:bg-gray-900 border-t border-gray-200 dark:border-gray-700"
+			role="contentinfo"
+		>
+			<div className="max-w-7xl mx-auto px-6 py-6">
+				<div className="flex flex-col md:flex-row justify-between items-center space-y-4 md:space-y-0">
+					<div className="text-gray-600 dark:text-gray-300 text-sm text-center md:text-left">
+						<p>
+							<a
+								href="https://x.com/simonluvramen"
+								target="_blank"
+								rel="noopener noreferrer"
+								className="inline-block bg-[linear-gradient(60deg,#39b6ff_0%,#bd45fb_33%,#ff5733_66%,#ffd600_100%)] bg-clip-text text-xs leading-none text-transparent font-mono transition-opacity duration-200 hover:opacity-85"
+							>
+								Simon.
+							</a>
+						</p>
+						<p className="text-gray-600 dark:text-gray-300 text-xs mt-0.5">
+							© 2026 page-agent. All rights reserved.
+						</p>
+					</div>
+
+					<div className="flex items-center">
+						<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 mr-4"
+						>
+							{isZh ? '使用条款与隐私' : 'Terms & Privacy'}
+						</a>
+						<a
+							href="https://x.com/simonluvramen"
+							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 mr-4"
+							aria-label="X (Twitter)"
+						>
+							<svg
+								role="img"
+								viewBox="0 0 24 24"
+								className="w-4 h-4 fill-current"
+								aria-hidden="true"
+							>
+								<path d={siX.path} />
+							</svg>
+						</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={isZh ? '访问 GitHub 仓库' : 'Visit GitHub repository'}
+						>
+							<svg
+								role="img"
+								viewBox="0 0 24 24"
+								className="w-5 h-5 fill-current"
+								aria-hidden="true"
+							>
+								<path d={siGithub.path} />
+							</svg>
+						</a>
+					</div>
+				</div>
+			</div>
+		</footer>
+	)
+}
diff --git a/packages/website/src/components/Header.tsx b/packages/website/src/components/Header.tsx
new file mode 100644
index 0000000..31a8ac9
--- /dev/null
+++ b/packages/website/src/components/Header.tsx
@@ -0,0 +1,188 @@
+import { BookOpen, Menu, X } from 'lucide-react'
+import { useState } from 'react'
+import { siGithub } from 'simple-icons'
+import { Link } from 'wouter'
+
+import { formatStars, useGitHubStars } from '@/hooks/useGitHubStars'
+import { useLanguage } from '@/i18n/context'
+
+import LanguageSwitcher from './LanguageSwitcher'
+import ThemeSwitcher from './ThemeSwitcher'
+import { HyperText } from './ui/hyper-text'
+
+export default function Header() {
+	const { isZh } = useLanguage()
+	const [mobileMenuOpen, setMobileMenuOpen] = useState(false)
+	const stars = useGitHubStars()
+
+	return (
+		<>
+			<header
+				className="sticky top-0 z-50 bg-white/80 dark:bg-gray-900/80 backdrop-blur-md border-b border-gray-200 dark:border-gray-700"
+				role="banner"
+			>
+				<div className="max-w-7xl mx-auto px-6 py-4">
+					<div className="flex items-center justify-between gap-2">
+						{/* Logo */}
+						<Link
+							href="/"
+							className="flex items-center gap-2 sm:gap-3 group shrink-0"
+							aria-label={isZh ? 'page-agent 首页' : 'page-agent home'}
+							onClick={() => setMobileMenuOpen(false)}
+						>
+							<img
+								src="https://page-agent.github.io/assets/brand/page-agent-color-128.webp"
+								alt="PageAgent Logo"
+								className="w-10 h-10 rounded-xl group-hover:scale-110 transition-transform duration-200"
+							/>
+							<div>
+								<span className="text-base sm:text-xl font-bold text-gray-900 dark:text-white leading-tight flex items-baseline gap-1.5">
+									page-agent
+									<span className="hidden sm:inline text-[10px] font-mono font-normal text-gray-400 dark:text-gray-500 tabular-nums before:content-['v']">
+										{import.meta.env.VERSION}
+									</span>
+								</span>
+								<HyperText
+									as="p"
+									className="hidden sm:block text-xs text-gray-600 dark:text-gray-300 py-0 font-normal overflow-visible"
+									duration={600}
+									animateOnHover={true}
+									aria-hidden="true"
+								>
+									AI Agent In Your Webpage
+								</HyperText>
+							</div>
+						</Link>
+
+						{/* Mobile Icon Navigation (横向滚动) */}
+						<nav
+							className="md:hidden flex items-center gap-1 overflow-x-auto scrollbar-hide flex-1"
+							role="navigation"
+							aria-label="Mobile navigation"
+						>
+							<Link
+								href="/docs/introduction/overview"
+								className="p-2 rounded-lg text-gray-600 dark:text-gray-300 hover:bg-gray-100 dark:hover:bg-gray-800 hover:text-blue-600 dark:hover:text-blue-400 transition-colors duration-200 shrink-0"
+								aria-label={isZh ? '文档' : 'Docs'}
+							>
+								<BookOpen className="w-5 h-5" />
+							</Link>
+							<a
+								href="https://github.com/alibaba/page-agent"
+								target="_blank"
+								rel="noopener noreferrer"
+								className="flex items-center gap-1 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="GitHub"
+							>
+								<svg
+									role="img"
+									viewBox="0 0 24 24"
+									className="w-5 h-5 fill-current"
+									aria-hidden="true"
+								>
+									<path d={siGithub.path} />
+								</svg>
+								{stars !== null && (
+									<span className="text-sm tabular-nums">★ {formatStars(stars)}</span>
+								)}
+							</a>
+						</nav>
+
+						{/* Desktop Navigation */}
+						<nav
+							className="hidden md:flex items-center space-x-6"
+							role="navigation"
+							aria-label={isZh ? '文档' : 'Docs'}
+						>
+							<Link
+								href="/docs/introduction/overview"
+								className="flex items-center gap-1.5 text-gray-600 dark:text-gray-300 hover:text-blue-600 dark:hover:text-blue-400 transition-colors duration-200"
+							>
+								<BookOpen className="w-4 h-4" />
+								{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="GitHub"
+							>
+								<svg
+									role="img"
+									viewBox="0 0 24 24"
+									className="w-4 h-4 fill-current"
+									aria-hidden="true"
+								>
+									<path d={siGithub.path} />
+								</svg>
+								GitHub
+								{stars !== null && (
+									<span className="text-sm font-medium tabular-nums ">★ {formatStars(stars)}</span>
+								)}
+							</a>
+							<ThemeSwitcher />
+							<LanguageSwitcher />
+						</nav>
+
+						{/* Mobile menu button */}
+						<button
+							type="button"
+							className="md:hidden p-2 rounded-lg text-gray-600 dark:text-gray-300 hover:bg-gray-100 dark:hover:bg-gray-800 transition-colors duration-200 shrink-0"
+							aria-label={isZh ? '打开导航栏' : 'Open navigation'}
+							aria-expanded={mobileMenuOpen}
+							aria-controls="mobile-menu"
+							onClick={() => setMobileMenuOpen(!mobileMenuOpen)}
+						>
+							{mobileMenuOpen ? <X className="w-6 h-6" /> : <Menu className="w-6 h-6" />}
+						</button>
+					</div>
+
+					{/* Mobile Navigation */}
+					{mobileMenuOpen && (
+						<nav
+							id="mobile-menu"
+							className="md:hidden pt-4 pb-2 space-y-3 border-t border-gray-200 dark:border-gray-700 mt-4"
+							role="navigation"
+						>
+							<Link
+								href="/docs/introduction/overview"
+								className="flex items-center gap-2 px-3 py-2 rounded-lg text-gray-600 dark:text-gray-300 hover:bg-gray-100 dark:hover:bg-gray-800 hover:text-blue-600 dark:hover:text-blue-400 transition-colors duration-200"
+								onClick={() => setMobileMenuOpen(false)}
+							>
+								<BookOpen className="w-5 h-5" />
+								{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="GitHub"
+							>
+								<svg
+									role="img"
+									viewBox="0 0 24 24"
+									className="w-5 h-5 fill-current"
+									aria-hidden="true"
+								>
+									<path d={siGithub.path} />
+								</svg>
+								GitHub
+								{stars !== null && (
+									<span className="text-xs tabular-nums text-gray-400 dark:text-gray-500">
+										★ {formatStars(stars)}
+									</span>
+								)}
+							</a>
+							<div className="flex items-center gap-3 px-3 py-2">
+								<ThemeSwitcher />
+								<LanguageSwitcher />
+							</div>
+						</nav>
+					)}
+				</div>
+			</header>
+		</>
+	)
+}
diff --git a/packages/website/src/components/Heading.tsx b/packages/website/src/components/Heading.tsx
new file mode 100644
index 0000000..2e15c80
--- /dev/null
+++ b/packages/website/src/components/Heading.tsx
@@ -0,0 +1,46 @@
+import { ComponentPropsWithoutRef, useEffect, useRef } from 'react'
+
+import { cn } from '@/lib/utils'
+
+type Level = 2 | 3 | 4
+
+interface HeadingProps extends Omit<ComponentPropsWithoutRef<'h2'>, 'children'> {
+	id: string
+	level?: Level
+	children: React.ReactNode
+}
+
+const levelStyles = {
+	2: { tag: 'h2', className: 'text-3xl font-semibold mb-4' },
+	3: { tag: 'h3', className: 'text-[1.375rem] font-semibold mb-3' },
+	4: { tag: 'h4', className: 'text-[1.0625rem] font-medium mb-2' },
+} 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>
+	)
+}
diff --git a/packages/website/src/components/HighlightSyntax.module.css b/packages/website/src/components/HighlightSyntax.module.css
new file mode 100644
index 0000000..4ced613
--- /dev/null
+++ b/packages/website/src/components/HighlightSyntax.module.css
@@ -0,0 +1,128 @@
+.syntax {
+	white-space: pre-wrap;
+	word-break: break-word;
+	overflow-wrap: break-word;
+	font-family: monospace;
+	font-size: 13px;
+	line-height: 1;
+	color: #171717;
+}
+
+:global(.dark) .syntax {
+	color: #e0e0e0;
+}
+
+/* JavaScript/TypeScript 关键字 */
+.keyword {
+	color: #d73a49;
+	font-weight: 600;
+}
+
+:global(.dark) .keyword {
+	color: #ff6b6b;
+}
+
+/* TypeScript 特定关键字 (interface, type, enum, etc.) */
+.tsKeyword {
+	color: #af00db;
+	font-weight: 600;
+}
+
+:global(.dark) .tsKeyword {
+	color: #c792ea;
+}
+
+/* TypeScript 内置类型 */
+.type {
+	color: #267f99;
+	font-weight: 500;
+}
+
+:global(.dark) .type {
+	color: #4ec9b0;
+}
+
+/* 字符串 */
+.string {
+	color: #1d6eca;
+}
+
+:global(.dark) .string {
+	color: #4fc3f7;
+}
+
+/* 数字 */
+.number {
+	color: #00c583;
+}
+
+:global(.dark) .number {
+	color: #66bb6a;
+}
+
+/* 布尔值和字面量 (true, false, null, undefined) */
+.literal {
+	color: #0000ff;
+	font-weight: 500;
+}
+
+:global(.dark) .literal {
+	color: #569cd6;
+}
+
+/* 注释 */
+.comment {
+	color: #6a737d;
+	font-style: italic;
+}
+
+:global(.dark) .comment {
+	color: #9e9e9e;
+}
+
+/* 装饰器 (@decorator) */
+.decorator {
+	color: #e0aa00;
+	font-weight: 500;
+}
+
+:global(.dark) .decorator {
+	color: #dcdcaa;
+}
+
+/* 箭头函数 (=>) */
+.arrow {
+	color: #d73a49;
+	font-weight: bold;
+}
+
+:global(.dark) .arrow {
+	color: #ff6b6b;
+}
+
+/* 标识符（变量名、函数名等） */
+.identifier {
+	color: #171717;
+}
+
+:global(.dark) .identifier {
+	color: #e0e0e0;
+}
+
+/* 属性访问 (.property) */
+.property {
+	color: #0550ae;
+}
+
+:global(.dark) .property {
+	color: #9cdcfe;
+}
+
+/* 运算符 */
+.operator {
+	color: #5a5a5a;
+}
+
+:global(.dark) .operator {
+	color: #d4d4d4;
+}
diff --git a/packages/website/src/components/HighlightSyntax.tsx b/packages/website/src/components/HighlightSyntax.tsx
new file mode 100644
index 0000000..052a838
--- /dev/null
+++ b/packages/website/src/components/HighlightSyntax.tsx
@@ -0,0 +1,175 @@
+/**
+ * js 语法高亮组件，适合在文章中演示代码片段
+ */
+import React from 'react'
+
+import styles from './HighlightSyntax.module.css'
+
+interface HighlightSyntaxProps {
+	code: string
+}
+
+// JavaScript/TypeScript 关键字
+const keywords =
+	'async|await|function|const|let|var|if|else|for|while|return|try|catch|finally|class|extends|from|import|export|default|undefined|throw|break|continue|switch|case|do|with|yield|delete|typeof|void|static|get|set|super|debugger'
+
+// TypeScript 特定关键字
+const tsKeywords =
+	'interface|type|enum|namespace|module|declare|abstract|implements|public|private|protected|readonly|as|satisfies|infer|keyof|is'
+
+// 布尔值和空值
+const literals = 'true|false|null|undefined|NaN|Infinity'
+
+// TypeScript 内置类型
+const tsTypes =
+	'string|number|boolean|any|unknown|never|void|object|symbol|bigint|Array|Promise|Record|Partial|Required|Readonly|Pick|Omit|Exclude|Extract|NonNullable|ReturnType|Parameters|ConstructorParameters|InstanceType|ThisType|Uppercase|Lowercase|Capitalize|Uncapitalize'
+
+// 辅助函数：转义 HTML 特殊字符
+function escapeHtml(text: string): string {
+	return text.replace(/&/g, '&').replace(/</g, '<').replace(/>/g, '>')
+}
+
+// 语法高亮函数，先提取 token 再转义和高亮
+function highlightSyntax(code: string): string {
+	// 构建正则模式，包含更多 token 类型（在原始文本上匹配）
+	const pattern = new RegExp(
+		'(' +
+			// 1. 字符串（双引号、单引号、模板字符串）
+			'"([^"\\\\]|\\\\.)*"|' +
+			"'([^'\\\\]|\\\\.)*'|" +
+			'`([^`\\\\]|\\\\.)*`|' +
+			// 2. 注释（单行和多行）
+			'//[^\\n]*|' +
+			'/\\*[\\s\\S]*?\\*/|' +
+			// 3. 装饰器
+			'@[a-zA-Z_$][\\w$]*|' +
+			// 4. 数字（包括小数、十六进制、科学计数法）
+			'\\b0[xX][0-9a-fA-F]+\\b|' +
+			'\\b\\d+\\.?\\d*(?:[eE][+-]?\\d+)?\\b|' +
+			// 5. TypeScript/JavaScript 关键字
+			'\\b(?:' +
+			keywords +
+			'|' +
+			tsKeywords +
+			'|' +
+			literals +
+			')\\b|' +
+			// 6. TypeScript 内置类型
+			'\\b(?:' +
+			tsTypes +
+			')\\b|' +
+			// 7. 箭头函数
+			'=>|' +
+			// 8. 函数调用（函数名后跟括号）
+			'\\b[a-zA-Z_$][\\w$]*(?=\\()|' +
+			// 9. 属性访问
+			'\\.[a-zA-Z_$][\\w$]*|' +
+			// 10. 运算符和特殊符号
+			'[+\\-*/%&|^!~<>=?:]+|' +
+			'[{}\\[\\]();,.]' +
+			')',
+		'g'
+	)
+
+	const tokens: string[] = []
+	let lastIndex = 0
+	let match: RegExpExecArray | null
+	while ((match = pattern.exec(code)) !== null) {
+		if (match.index > lastIndex) {
+			const gap = code.slice(lastIndex, match.index)
+			// 将间隙按空白符分割，保留空白符
+			tokens.push(...gap.split(/(\s+)/))
+		}
+		tokens.push(match[0])
+		lastIndex = pattern.lastIndex
+	}
+	if (lastIndex < code.length) {
+		tokens.push(...code.slice(lastIndex).split(/(\s+)/))
+	}
+
+	const highlighted = tokens
+		.map((token) => {
+			// 空白符直接返回
+			if (/^\s+$/.test(token)) {
+				return token
+			}
+
+			// 1. 注释（单行和多行）
+			if (/^\/\/.*$/.test(token) || /^\/\*[\s\S]*?\*\/$/.test(token)) {
+				return `<span class="${styles.comment}">${escapeHtml(token)}</span>`
+			}
+
+			// 2. 字符串
+			if (
+				/^"([^"\\]|\\.)*"$/.test(token) ||
+				/^'([^'\\]|\\.)*'$/.test(token) ||
+				/^`([^`\\]|\\.)*`$/.test(token)
+			) {
+				return `<span class="${styles.string}">${escapeHtml(token)}</span>`
+			}
+
+			// 3. 数字
+			if (/^(0[xX][0-9a-fA-F]+|\d+\.?\d*(?:[eE][+-]?\d+)?)$/.test(token)) {
+				return `<span class="${styles.number}">${escapeHtml(token)}</span>`
+			}
+
+			// 4. 布尔值和特殊字面量
+			if (new RegExp(`^(?:${literals})$`).test(token)) {
+				return `<span class="${styles.literal}">${escapeHtml(token)}</span>`
+			}
+
+			// 5. JavaScript/TypeScript 关键字
+			if (new RegExp(`^(?:${keywords})$`).test(token)) {
+				return `<span class="${styles.keyword}">${escapeHtml(token)}</span>`
+			}
+
+			// 6. TypeScript 特定关键字
+			if (new RegExp(`^(?:${tsKeywords})$`).test(token)) {
+				return `<span class="${styles.tsKeyword}">${escapeHtml(token)}</span>`
+			}
+
+			// 7. TypeScript 内置类型
+			if (new RegExp(`^(?:${tsTypes})$`).test(token)) {
+				return `<span class="${styles.type}">${escapeHtml(token)}</span>`
+			}
+
+			// 8. 装饰器
+			if (/^@[a-zA-Z_$][\w$]*$/.test(token)) {
+				return `<span class="${styles.decorator}">${escapeHtml(token)}</span>`
+			}
+
+			// 9. 箭头函数
+			if (token === '=>') {
+				return `<span class="${styles.arrow}">${escapeHtml(token)}</span>`
+			}
+
+			// 10. 函数调用和标识符
+			if (/^[a-zA-Z_$][\w$]*$/.test(token)) {
+				return `<span class="${styles.identifier}">${escapeHtml(token)}</span>`
+			}
+
+			// 11. 属性访问
+			if (/^\.[a-zA-Z_$][\w$]*$/.test(token)) {
+				return `<span class="${styles.property}">${escapeHtml(token)}</span>`
+			}
+
+			// 12. 运算符
+			if (/^[+\-*/%&|^!~<>=?:]+$/.test(token)) {
+				return `<span class="${styles.operator}">${escapeHtml(token)}</span>`
+			}
+
+			// 13. 其他符号，需要转义
+			return escapeHtml(token)
+		})
+		.join('')
+
+	return highlighted
+}
+
+const HighlightSyntaxClient: React.FC<HighlightSyntaxProps> = ({ code }) => {
+	const htmlContent = highlightSyntax(code)
+
+	return <code className={styles.syntax} dangerouslySetInnerHTML={{ __html: htmlContent }} />
+}
+
+export default HighlightSyntaxClient
diff --git a/packages/website/src/components/JSConsole.module.css b/packages/website/src/components/JSConsole.module.css
new file mode 100644
index 0000000..9675370
--- /dev/null
+++ b/packages/website/src/components/JSConsole.module.css
@@ -0,0 +1,164 @@
+.console {
+	display: flex;
+	flex-direction: column;
+	background-color: #ffffff;
+	border: 1px solid #e0e0e0;
+	border-radius: 8px;
+	font-family: monospace;
+	font-size: 12px;
+	line-height: 1;
+	overflow: hidden;
+	scroll-behavior: none;
+	box-shadow: 0 2px 8px rgba(0, 0, 0, 0.1);
+}
+
+.historyArea {
+	flex: 1;
+	overflow-y: auto;
+	padding: 12px;
+	background-color: #fafafa;
+	min-height: 200px;
+	display: flex;
+	flex-direction: column;
+
+	scroll-behavior: contain;
+
+	&::-webkit-scrollbar {
+		width: 6px;
+	}
+
+	&::-webkit-scrollbar-track {
+		background: transparent;
+	}
+
+	&::-webkit-scrollbar-thumb {
+		background-color: #d0d0d0;
+		border-radius: 3px;
+	}
+
+	&::-webkit-scrollbar-thumb:hover {
+		background-color: #b0b0b0;
+	}
+
+	.historyItem {
+		display: flex;
+		align-items: center;
+
+		font-size: 12px;
+		line-height: 1;
+		padding-bottom: 6px;
+		border-bottom: #ccdeeebd 1px solid;
+		margin-bottom: 6px;
+
+		flex: 0 0 auto;
+
+		&:last-child {
+			margin-bottom: 0;
+			border-bottom: none;
+		}
+
+		&.input {
+		}
+		&.output {
+		}
+
+		.content {
+			margin: 0;
+			white-space: pre-wrap;
+			word-break: break-word;
+			flex: 1;
+			font-family: inherit;
+			font-size: inherit;
+			line-height: inherit;
+			color: #2563eb;
+		}
+
+		/* 错误样式 */
+		&.error .content {
+			color: #dc2626;
+			background-color: #fef2f2;
+			padding: 4px 8px;
+			border-radius: 4px;
+			border-left: 3px solid #dc2626;
+		}
+	}
+}
+
+.prompt {
+	display: flex;
+	height: 100%;
+	align-items: flex-start;
+	width: 12px;
+	color: #666;
+	margin-right: 8px;
+	font-weight: 500;
+	flex-shrink: 0;
+	user-select: none;
+}
+
+.executing {
+	color: #f59e0b;
+	font-style: italic;
+	animation: pulse 1.5s ease-in-out infinite;
+}
+
+@keyframes pulse {
+	0%,
+	100% {
+		opacity: 1;
+	}
+	50% {
+		opacity: 0.5;
+	}
+}
+
+.inputArea {
+	display: flex;
+	align-items: center;
+
+	padding: 12px;
+	background-color: #ffffff;
+	border-top: 1px solid #e0e0e0;
+
+	.prompt {
+		margin-top: 8px;
+	}
+
+	.input {
+		flex: auto;
+		border: none;
+		outline: none;
+		background: transparent;
+		color: #333;
+		resize: none;
+
+		line-height: 20px;
+	}
+
+	.input::placeholder {
+		color: #999;
+		font-style: italic;
+	}
+
+	.input:disabled {
+		opacity: 0.6;
+		cursor: not-allowed;
+	}
+}
+
+/* 响应式设计 */
+@media (max-width: 768px) {
+	.console {
+		font-size: 12px;
+		border-radius: 6px;
+	}
+
+	.historyArea,
+	.inputLine {
+		padding: 8px;
+	}
+
+	.prompt {
+		margin-right: 6px;
+	}
+}
diff --git a/packages/website/src/components/JSConsole.tsx b/packages/website/src/components/JSConsole.tsx
new file mode 100644
index 0000000..d636337
--- /dev/null
+++ b/packages/website/src/components/JSConsole.tsx
@@ -0,0 +1,371 @@
+/**
+ * JS 调试台，适合在文档中直接让用户运行代码，并且实时查看运行结果
+ */
+/* eslint-disable @typescript-eslint/no-base-to-string */
+import { KeyboardEvent, useEffect, useImperativeHandle, useRef, useState } from 'react'
+
+import HighlightSyntax from './HighlightSyntax'
+
+import styles from './JSConsole.module.css'
+
+// 全局console拦截管理器
+class ConsoleInterceptor {
+	private static instance: ConsoleInterceptor
+	private subscribers = new Set<(type: string, args: unknown[]) => void>()
+	private originalConsole: {
+		log: typeof console.log
+		warn: typeof console.warn
+		error: typeof console.error
+	}
+	private isIntercepting = false
+
+	private constructor() {
+		this.originalConsole = {
+			log: console.log.bind(console),
+			warn: console.warn.bind(console),
+			error: console.error.bind(console),
+		}
+	}
+
+	static getInstance() {
+		if (!ConsoleInterceptor.instance) {
+			ConsoleInterceptor.instance = new ConsoleInterceptor()
+		}
+		return ConsoleInterceptor.instance
+	}
+
+	subscribe(callback: (type: string, args: unknown[]) => void) {
+		this.subscribers.add(callback)
+		this.startIntercepting()
+	}
+
+	unsubscribe(callback: (type: string, args: unknown[]) => void) {
+		this.subscribers.delete(callback)
+		if (this.subscribers.size === 0) {
+			this.stopIntercepting()
+		}
+	}
+
+	private startIntercepting() {
+		if (this.isIntercepting) return
+
+		this.isIntercepting = true
+
+		console.log = (...args: unknown[]) => {
+			this.originalConsole.log(...args)
+			this.notifySubscribers('log', args)
+		}
+
+		console.warn = (...args: unknown[]) => {
+			this.originalConsole.warn(...args)
+			this.notifySubscribers('warn', args)
+		}
+
+		console.error = (...args: unknown[]) => {
+			this.originalConsole.error(...args)
+			this.notifySubscribers('error', args)
+		}
+	}
+
+	private stopIntercepting() {
+		if (!this.isIntercepting) return
+
+		this.isIntercepting = false
+		console.log = this.originalConsole.log
+		console.warn = this.originalConsole.warn
+		console.error = this.originalConsole.error
+	}
+
+	private notifySubscribers(type: string, args: unknown[]) {
+		this.subscribers.forEach((callback) => {
+			callback(type, args)
+		})
+	}
+}
+
+interface JSConsoleProps {
+	context?: Record<string, unknown>
+	height?: string
+	onExecute?: (code: string, result: unknown) => void
+	placeholder?: string
+	ref?: React.Ref<JSConsoleRef>
+}
+
+export interface JSConsoleRef {
+	executeCode: (code: string) => Promise<unknown>
+	clear: () => void
+	appendOutput: (content: string) => void
+}
+
+interface OutputItem {
+	type: 'input' | 'output' | 'error' | 'log'
+	content: string
+	timestamp: number
+}
+
+const DEFAULT_CONTEXT = {}
+
+function JSConsole({
+	context = DEFAULT_CONTEXT,
+	height = '400px',
+	onExecute,
+	placeholder = 'Enter JavaScript code...',
+	ref,
+}: JSConsoleProps) {
+	const [input, setInput] = useState('')
+	const [outputs, setOutputs] = useState<OutputItem[]>([])
+	const [isExecuting, setIsExecuting] = useState(false)
+	const inputRef = useRef<HTMLTextAreaElement>(null)
+	const outputRef = useRef<HTMLDivElement>(null)
+
+	// 持久的执行上下文，用于多轮对话共享作用域
+	const executionContextRef = useRef<Record<string, unknown>>({})
+
+	// 格式化结果
+	const formatResult = (value: unknown): string => {
+		if (value === null) return 'null'
+		if (value === undefined) return 'undefined'
+		if (typeof value === 'string') return `"${value}"`
+		if (typeof value === 'function') return `[Function: ${value.name || 'anonymous'}]`
+		if (typeof value === 'object') {
+			try {
+				return JSON.stringify(value, null, 2)
+			} catch {
+				return value.toString()
+			}
+		}
+		return String(value)
+	}
+
+	// 全局console拦截处理
+	useEffect(() => {
+		const interceptor = ConsoleInterceptor.getInstance()
+		let scrollTimer: ReturnType<typeof setTimeout>
+
+		const handleGlobalConsole = (type: string, args: unknown[]) => {
+			const content = args.map((arg) => formatResult(arg)).join(' ')
+
+			const outputItem: OutputItem = {
+				type: type as any,
+				content: content,
+				timestamp: Date.now(),
+			}
+
+			setOutputs((prev) => [...prev, outputItem])
+
+			clearTimeout(scrollTimer)
+			scrollTimer = setTimeout(() => {
+				if (outputRef.current) {
+					outputRef.current.scrollTop = outputRef.current.scrollHeight
+				}
+			}, 0)
+		}
+
+		interceptor.subscribe(handleGlobalConsole)
+
+		return () => {
+			interceptor.unsubscribe(handleGlobalConsole)
+			clearTimeout(scrollTimer)
+		}
+	}, [])
+
+	// 执行代码
+	const executeCode = async (code: string): Promise<unknown> => {
+		if (!code.trim()) return
+
+		setIsExecuting(true)
+
+		// 添加输入到输出
+		const inputItem: OutputItem = {
+			type: 'input',
+			content: code,
+			timestamp: Date.now(),
+		}
+
+		setOutputs((prev) => [...prev, inputItem])
+
+		try {
+			// 创建异步函数以支持 await
+			const AsyncFunction = Object.getPrototypeOf(async function () {}).constructor
+
+			// 合并外部上下文和持久执行上下文
+			const allContext = { ...context, ...executionContextRef.current }
+			const contextKeys = Object.keys(allContext)
+			const contextValues = Object.values(allContext)
+
+			// 注入 console.log 重定向
+			const logs: string[] = []
+			const mockConsole = {
+				log: (...args: unknown[]) => {
+					logs.push(args.map((arg) => formatResult(arg)).join(' '))
+				},
+				error: (...args: unknown[]) => {
+					logs.push('ERROR: ' + args.map((arg) => formatResult(arg)).join(' '))
+				},
+				warn: (...args: unknown[]) => {
+					logs.push('WARN: ' + args.map((arg) => formatResult(arg)).join(' '))
+				},
+			}
+
+			// 检测代码是否是表达式还是语句
+			const trimmedCode = code.trim()
+			const isExpression =
+				!trimmedCode.includes(';') &&
+				!trimmedCode.startsWith('const ') &&
+				!trimmedCode.startsWith('let ') &&
+				!trimmedCode.startsWith('var ') &&
+				!trimmedCode.startsWith('function ') &&
+				!trimmedCode.startsWith('class ') &&
+				!trimmedCode.startsWith('if ') &&
+				!trimmedCode.startsWith('for ') &&
+				!trimmedCode.startsWith('while ') &&
+				!trimmedCode.startsWith('try ') &&
+				!trimmedCode.startsWith('{') &&
+				!trimmedCode.includes('\n')
+
+			// 如果是表达式，自动添加 return
+			const codeToExecute = isExpression ? `return ${code}` : code
+
+			const wrappedCode = `
+					return (async function() {
+						${codeToExecute}
+					})();
+				`
+
+			// 执行代码
+			const func = new AsyncFunction('console', ...contextKeys, wrappedCode)
+			const result = await func(mockConsole, ...contextValues)
+
+			// 添加 console.log 输出
+			if (logs.length > 0) {
+				const logItem: OutputItem = {
+					type: 'log',
+					content: logs.join('\n'),
+					timestamp: Date.now(),
+				}
+				setOutputs((prev) => [...prev, logItem])
+			}
+
+			// 总是添加执行结果输出（包括 undefined）
+			const outputItem: OutputItem = {
+				type: 'output',
+				content: formatResult(result),
+				timestamp: Date.now(),
+			}
+			setOutputs((prev) => [...prev, outputItem])
+
+			onExecute?.(code, result)
+			return result
+		} catch (error) {
+			const errorItem: OutputItem = {
+				type: 'error',
+				content: error instanceof Error ? error.message : String(error),
+				timestamp: Date.now(),
+			}
+			setOutputs((prev) => [...prev, errorItem])
+			throw error
+		} finally {
+			setIsExecuting(false)
+			// 滚动到底部
+			setTimeout(() => {
+				if (outputRef.current) {
+					outputRef.current.scrollTop = outputRef.current.scrollHeight
+				}
+			}, 0)
+		}
+	}
+
+	// 清空控制台
+	const clear = () => {
+		setOutputs([])
+		// 同时清空执行上下文
+		executionContextRef.current = {}
+	}
+
+	// 添加输出
+	const appendOutput = (content: string) => {
+		const outputItem: OutputItem = {
+			type: 'output',
+			content,
+			timestamp: Date.now(),
+		}
+		setOutputs((prev) => [...prev, outputItem])
+	}
+
+	// 暴露方法给父组件
+	useImperativeHandle(ref, () => ({
+		executeCode,
+		clear,
+		appendOutput,
+	}))
+
+	// 处理键盘事件
+	const handleKeyDown = (e: KeyboardEvent<HTMLTextAreaElement>) => {
+		if (e.key === 'Enter') {
+			if (e.shiftKey) {
+				// Shift+Enter 换行
+				return
+			} else {
+				// Enter 执行
+				e.preventDefault()
+				if (!isExecuting && input.trim()) {
+					executeCode(input)
+					setInput('')
+					setTimeout(() => inputRef.current?.focus(), 0)
+				}
+			}
+		}
+	}
+
+	function getPrompt(type: string) {
+		let prompt = ' '
+		if (type === 'input') {
+			prompt = '>'
+		} else if (type === 'output') {
+			prompt = '<'
+		}
+		return prompt
+	}
+
+	return (
+		<div className={styles.console} style={{ height }}>
+			{/* 历史记录和输入区域 */}
+			<div className={styles.historyArea} ref={outputRef}>
+				{outputs.map((item) => (
+					<div key={item.timestamp} className={`${styles.historyItem} ${styles[item.type]}`}>
+						<span className={styles.prompt}>{getPrompt(item.type)}</span>
+						<pre className={styles.content}>
+							<HighlightSyntax code={item.content} />
+						</pre>
+					</div>
+				))}
+				{isExecuting && (
+					<div className={styles.historyItem}>
+						<span className={styles.prompt}>{'> '}</span>
+						<span className={styles.executing}>Executing...</span>
+					</div>
+				)}
+			</div>
+
+			{/* 当前输入行 */}
+			<div className={styles.inputArea}>
+				<span className={styles.prompt}>{'> '}</span>
+				<textarea
+					ref={inputRef}
+					className={styles.input}
+					value={input}
+					onChange={(e) => setInput(e.target.value)}
+					onKeyDown={handleKeyDown}
+					placeholder={placeholder}
+					disabled={isExecuting}
+					rows={1}
+					style={{
+						height: Math.min(Math.max(20, input.split('\n').length * 20), 120),
+					}}
+				/>
+			</div>
+		</div>
+	)
+}
+
+export default JSConsole
diff --git a/packages/website/src/components/LanguageSwitcher.tsx b/packages/website/src/components/LanguageSwitcher.tsx
new file mode 100644
index 0000000..8c73eff
--- /dev/null
+++ b/packages/website/src/components/LanguageSwitcher.tsx
@@ -0,0 +1,114 @@
+import { useEffect, useRef, useState } from 'react'
+
+import { useLanguage } from '@/i18n/context'
+
+export default function LanguageSwitcher() {
+	const { language, isZh, setLanguage } = useLanguage()
+	const [isOpen, setIsOpen] = useState(false)
+	const dropdownRef = useRef<HTMLDivElement>(null)
+
+	const languages = [
+		{ code: 'en-US' as const, label: 'English' },
+		{ code: 'zh-CN' as const, label: '中文' },
+	]
+
+	const currentLanguage = languages.find((lang) => lang.code === language) || languages[0]
+
+	const handleLanguageChange = (langCode: 'zh-CN' | 'en-US') => {
+		setLanguage(langCode)
+		setIsOpen(false)
+	}
+
+	// Close dropdown when clicking outside
+	useEffect(() => {
+		const handleClickOutside = (event: MouseEvent) => {
+			if (dropdownRef.current && !dropdownRef.current.contains(event.target as Node)) {
+				setIsOpen(false)
+			}
+		}
+
+		if (isOpen) {
+			document.addEventListener('mousedown', handleClickOutside)
+		}
+
+		return () => {
+			document.removeEventListener('mousedown', handleClickOutside)
+		}
+	}, [isOpen])
+
+	return (
+		<div className="relative" ref={dropdownRef}>
+			<button
+				onClick={() => setIsOpen(!isOpen)}
+				className="flex cursor-pointer items-center gap-2 rounded-lg border border-gray-200 bg-gray-100 px-3 py-1.5 text-sm font-medium text-gray-700 transition-colors hover:bg-gray-200 dark:border-gray-700 dark:bg-gray-800 dark:text-gray-300 dark:hover:bg-gray-700"
+				aria-label={isZh ? '切换语言' : 'Switch language'}
+				aria-expanded={isOpen}
+				aria-haspopup="true"
+			>
+				<svg
+					className="w-4 h-4"
+					fill="none"
+					stroke="currentColor"
+					viewBox="0 0 24 24"
+					aria-hidden="true"
+				>
+					<path
+						strokeLinecap="round"
+						strokeLinejoin="round"
+						strokeWidth={2}
+						d="M3 5h12M9 3v2m1.048 9.5A18.022 18.022 0 016.412 9m6.088 9h7M11 21l5-10 5 10M12.751 5C11.783 10.77 8.07 15.61 3 18.129"
+					/>
+				</svg>
+				<span>{currentLanguage.label}</span>
+				<svg
+					className={`w-4 h-4 transition-transform duration-200 ${isOpen ? 'rotate-180' : ''}`}
+					fill="none"
+					stroke="currentColor"
+					viewBox="0 0 24 24"
+					aria-hidden="true"
+				>
+					<path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M19 9l-7 7-7-7" />
+				</svg>
+			</button>
+
+			{isOpen && (
+				<div
+					className="absolute right-0 mt-2 w-40 bg-white dark:bg-gray-800 rounded-lg shadow-lg border border-gray-200 dark:border-gray-700 py-1 z-50"
+					role="menu"
+					aria-orientation="vertical"
+				>
+					{languages.map((lang) => (
+						<button
+							key={lang.code}
+							onClick={() => handleLanguageChange(lang.code)}
+							className={`flex w-full cursor-pointer items-center gap-2 px-4 py-2 text-left text-sm transition-colors hover:bg-gray-100 dark:hover:bg-gray-700 ${
+								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>
+							{language === lang.code && (
+								<svg
+									className="w-4 h-4 ml-auto"
+									fill="none"
+									stroke="currentColor"
+									viewBox="0 0 24 24"
+									aria-hidden="true"
+								>
+									<path
+										strokeLinecap="round"
+										strokeLinejoin="round"
+										strokeWidth={2}
+										d="M5 13l4 4L19 7"
+									/>
+								</svg>
+							)}
+						</button>
+					))}
+				</div>
+			)}
+		</div>
+	)
+}
diff --git a/packages/website/src/components/ThemeSwitcher.tsx b/packages/website/src/components/ThemeSwitcher.tsx
new file mode 100644
index 0000000..c875a3a
--- /dev/null
+++ b/packages/website/src/components/ThemeSwitcher.tsx
@@ -0,0 +1,134 @@
+import { useEffect, useState } from 'react'
+
+type Theme = 'light' | 'dark'
+
+export default function ThemeSwitcher() {
+	const [theme, setTheme] = useState<Theme>(() => {
+		// 初始化时读取保存的主题
+		if (typeof window !== 'undefined') {
+			const savedTheme = localStorage.getItem('theme') as Theme | null
+			if (savedTheme === 'light' || savedTheme === 'dark') {
+				return savedTheme
+			}
+			// 默认跟随系统
+			return window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light'
+		}
+		return 'light'
+	})
+
+	useEffect(() => {
+		// 应用主题
+		if (theme === 'dark') {
+			document.documentElement.classList.add('dark')
+			document.documentElement.style.colorScheme = 'dark'
+		} else {
+			document.documentElement.classList.remove('dark')
+			document.documentElement.style.colorScheme = 'light'
+		}
+		// 保存到 localStorage
+		localStorage.setItem('theme', theme)
+	}, [theme])
+
+	// 监听系统主题变化
+	useEffect(() => {
+		const mediaQuery = window.matchMedia('(prefers-color-scheme: dark)')
+
+		const handleSystemThemeChange = (e: MediaQueryListEvent) => {
+			// 只有在用户未手动设置时才自动跟随系统
+			const savedTheme = localStorage.getItem('theme')
+			if (!savedTheme) {
+				setTheme(e.matches ? 'dark' : 'light')
+			}
+		}
+
+		mediaQuery.addEventListener('change', handleSystemThemeChange)
+		return () => mediaQuery.removeEventListener('change', handleSystemThemeChange)
+	}, [])
+
+	const toggleTheme = () => {
+		setTheme((prev) => (prev === 'light' ? 'dark' : 'light'))
+	}
+
+	return (
+		<button
+			onClick={toggleTheme}
+			className="relative inline-flex h-8 w-16 cursor-pointer items-center rounded-full transition-colors duration-300 ease-in-out focus:outline-none"
+			style={{
+				backgroundColor: theme === 'dark' ? '#1e293b' : '#e0f2fe',
+			}}
+			aria-label={theme === 'light' ? 'Switch to dark mode' : 'Switch to light mode'}
+			role="switch"
+			aria-checked={theme === 'dark'}
+		>
+			{/* 滑块 */}
+			<span
+				className={`inline-block h-6 w-6 rounded-full transition-all duration-300 ease-in-out shadow-md ${
+					theme === 'dark' ? 'translate-x-9' : 'translate-x-1'
+				}`}
+				style={{
+					backgroundColor: theme === 'dark' ? '#475569' : '#fbbf24',
+				}}
+			>
+				{/* 图标 */}
+				<span className="flex items-center justify-center h-full w-full">
+					{theme === 'light' ? (
+						// 太阳图标
+						<svg
+							className="w-4 h-4 text-white"
+							fill="currentColor"
+							viewBox="0 0 20 20"
+							aria-hidden="true"
+						>
+							<path
+								fillRule="evenodd"
+								d="M10 2a1 1 0 011 1v1a1 1 0 11-2 0V3a1 1 0 011-1zm4 8a4 4 0 11-8 0 4 4 0 018 0zm-.464 4.95l.707.707a1 1 0 001.414-1.414l-.707-.707a1 1 0 00-1.414 1.414zm2.12-10.607a1 1 0 010 1.414l-.706.707a1 1 0 11-1.414-1.414l.707-.707a1 1 0 011.414 0zM17 11a1 1 0 100-2h-1a1 1 0 100 2h1zm-7 4a1 1 0 011 1v1a1 1 0 11-2 0v-1a1 1 0 011-1zM5.05 6.464A1 1 0 106.465 5.05l-.708-.707a1 1 0 00-1.414 1.414l.707.707zm1.414 8.486l-.707.707a1 1 0 01-1.414-1.414l.707-.707a1 1 0 011.414 1.414zM4 11a1 1 0 100-2H3a1 1 0 000 2h1z"
+								clipRule="evenodd"
+							/>
+						</svg>
+					) : (
+						// 月亮图标
+						<svg
+							className="w-4 h-4 text-slate-200"
+							fill="currentColor"
+							viewBox="0 0 20 20"
+							aria-hidden="true"
+						>
+							<path d="M17.293 13.293A8 8 0 016.707 2.707a8.001 8.001 0 1010.586 10.586z" />
+						</svg>
+					)}
+				</span>
+			</span>
+
+			{/* 背景装饰 */}
+			<span
+				className="absolute inset-0 flex items-center justify-between px-2 pointer-events-none"
+				aria-hidden="true"
+			>
+				{/* 左侧太阳（浅色模式时显示） */}
+				<span
+					className={`transition-opacity duration-300 ${
+						theme === 'light' ? 'opacity-0' : 'opacity-40'
+					}`}
+				>
+					<svg className="w-4 h-4 text-sky-400" fill="currentColor" viewBox="0 0 20 20">
+						<path
+							fillRule="evenodd"
+							d="M10 2a1 1 0 011 1v1a1 1 0 11-2 0V3a1 1 0 011-1zm4 8a4 4 0 11-8 0 4 4 0 018 0zm-.464 4.95l.707.707a1 1 0 001.414-1.414l-.707-.707a1 1 0 00-1.414 1.414zm2.12-10.607a1 1 0 010 1.414l-.706.707a1 1 0 11-1.414-1.414l.707-.707a1 1 0 011.414 0zM17 11a1 1 0 100-2h-1a1 1 0 100 2h1zm-7 4a1 1 0 011 1v1a1 1 0 11-2 0v-1a1 1 0 011-1zM5.05 6.464A1 1 0 106.465 5.05l-.708-.707a1 1 0 00-1.414 1.414l.707.707zm1.414 8.486l-.707.707a1 1 0 01-1.414-1.414l.707-.707a1 1 0 011.414 1.414zM4 11a1 1 0 100-2H3a1 1 0 000 2h1z"
+							clipRule="evenodd"
+						/>
+					</svg>
+				</span>
+				{/* 右侧月亮（深色模式时显示） */}
+				<span
+					className={`transition-opacity duration-300 ${
+						theme === 'dark' ? 'opacity-0' : 'opacity-40'
+					}`}
+				>
+					<svg className="w-4 h-4 text-slate-400" fill="currentColor" viewBox="0 0 20 20">
+						<path d="M17.293 13.293A8 8 0 016.707 2.707a8.001 8.001 0 1010.586 10.586z" />
+					</svg>
+				</span>
+			</span>
+		</button>
+	)
+}
diff --git a/packages/website/src/components/ui/alert.tsx b/packages/website/src/components/ui/alert.tsx
new file mode 100644
index 0000000..c8f7862
--- /dev/null
+++ b/packages/website/src/components/ui/alert.tsx
@@ -0,0 +1,60 @@
+import { type VariantProps, cva } from 'class-variance-authority'
+import * as React from 'react'
+
+import { cn } from '@/lib/utils'
+
+const alertVariants = cva(
+	'relative w-full rounded-lg border px-4 py-3 text-sm grid has-[>svg]:grid-cols-[calc(var(--spacing)*4)_1fr] grid-cols-[0_1fr] has-[>svg]:gap-x-3 gap-y-0.5 items-start [&>svg]:size-4 [&>svg]:translate-y-0.5 [&>svg]:text-current',
+	{
+		variants: {
+			variant: {
+				default: 'bg-card text-card-foreground',
+				destructive:
+					'text-destructive bg-card [&>svg]:text-current *:data-[slot=alert-description]:text-destructive/90',
+			},
+		},
+		defaultVariants: {
+			variant: 'default',
+		},
+	}
+)
+
+function Alert({
+	className,
+	variant,
+	...props
+}: React.ComponentProps<'div'> & VariantProps<typeof alertVariants>) {
+	return (
+		<div
+			data-slot="alert"
+			role="alert"
+			className={cn(alertVariants({ variant }), className)}
+			{...props}
+		/>
+	)
+}
+
+function AlertTitle({ className, ...props }: React.ComponentProps<'div'>) {
+	return (
+		<div
+			data-slot="alert-title"
+			className={cn('col-start-2 line-clamp-1 min-h-4 font-medium tracking-tight', className)}
+			{...props}
+		/>
+	)
+}
+
+function AlertDescription({ className, ...props }: React.ComponentProps<'div'>) {
+	return (
+		<div
+			data-slot="alert-description"
+			className={cn(
+				'text-muted-foreground col-start-2 grid justify-items-start gap-1 text-sm [&_p]:leading-relaxed',
+				className
+			)}
+			{...props}
+		/>
+	)
+}
+
+export { Alert, AlertTitle, AlertDescription }
diff --git a/packages/website/src/components/ui/animated-gradient-text.tsx b/packages/website/src/components/ui/animated-gradient-text.tsx
new file mode 100644
index 0000000..8e2de7c
--- /dev/null
+++ b/packages/website/src/components/ui/animated-gradient-text.tsx
@@ -0,0 +1,37 @@
+import { ComponentPropsWithoutRef } from 'react'
+
+import { cn } from '@/lib/utils'
+
+export interface AnimatedGradientTextProps extends ComponentPropsWithoutRef<'div'> {
+	speed?: number
+	colorFrom?: string
+	colorTo?: string
+}
+
+export function AnimatedGradientText({
+	children,
+	className,
+	speed = 1,
+	colorFrom = '#ffaa40',
+	colorTo = '#9c40ff',
+	...props
+}: AnimatedGradientTextProps) {
+	return (
+		<span
+			style={
+				{
+					'--bg-size': `${speed * 300}%`,
+					'--color-from': colorFrom,
+					'--color-to': colorTo,
+				} as React.CSSProperties
+			}
+			className={cn(
+				`animate-gradient inline bg-gradient-to-r from-[var(--color-from)] via-[var(--color-to)] to-[var(--color-from)] bg-[length:var(--bg-size)_100%] bg-clip-text text-transparent`,
+				className
+			)}
+			{...props}
+		>
+			{children}
+		</span>
+	)
+}
diff --git a/packages/website/src/components/ui/animated-shiny-text.tsx b/packages/website/src/components/ui/animated-shiny-text.tsx
new file mode 100644
index 0000000..899baae
--- /dev/null
+++ b/packages/website/src/components/ui/animated-shiny-text.tsx
@@ -0,0 +1,38 @@
+import { CSSProperties, ComponentPropsWithoutRef, FC } from 'react'
+
+import { cn } from '@/lib/utils'
+
+export interface AnimatedShinyTextProps extends ComponentPropsWithoutRef<'span'> {
+	shimmerWidth?: number
+}
+
+export const AnimatedShinyText: FC<AnimatedShinyTextProps> = ({
+	children,
+	className,
+	shimmerWidth = 100,
+	...props
+}) => {
+	return (
+		<span
+			style={
+				{
+					'--shiny-width': `${shimmerWidth}px`,
+				} as CSSProperties
+			}
+			className={cn(
+				'mx-auto max-w-md text-neutral-600/70 dark:text-neutral-400/70',
+
+				// Shine effect
+				'animate-shiny-text [background-size:var(--shiny-width)_100%] bg-clip-text [background-position:0_0] bg-no-repeat [transition:background-position_1s_cubic-bezier(.6,.6,0,1)_infinite]',
+
+				// Shine gradient
+				'bg-gradient-to-r from-transparent via-black/80 via-50% to-transparent dark:via-white/80',
+
+				className
+			)}
+			{...props}
+		>
+			{children}
+		</span>
+	)
+}
diff --git a/packages/website/src/components/ui/aurora-text.tsx b/packages/website/src/components/ui/aurora-text.tsx
new file mode 100644
index 0000000..9a537d0
--- /dev/null
+++ b/packages/website/src/components/ui/aurora-text.tsx
@@ -0,0 +1,39 @@
+import React, { memo } from 'react'
+
+interface AuroraTextProps {
+	children: React.ReactNode
+	className?: string
+	colors?: string[]
+	speed?: number
+}
+
+export const AuroraText = memo(
+	({
+		children,
+		className = '',
+		colors = ['#FF0080', '#7928CA', '#0070F3', '#38bdf8'],
+		speed = 1,
+	}: AuroraTextProps) => {
+		const gradientStyle = {
+			backgroundImage: `linear-gradient(135deg, ${colors.join(', ')}, ${colors[0]})`,
+			WebkitBackgroundClip: 'text',
+			WebkitTextFillColor: 'transparent',
+			animationDuration: `${10 / speed}s`,
+		}
+
+		return (
+			<span className={`relative inline-block ${className}`}>
+				<span className="sr-only">{children}</span>
+				<span
+					className="animate-aurora relative bg-[length:200%_auto] bg-clip-text text-transparent"
+					style={gradientStyle}
+					aria-hidden="true"
+				>
+					{children}
+				</span>
+			</span>
+		)
+	}
+)
+
+AuroraText.displayName = 'AuroraText'
diff --git a/packages/website/src/components/ui/badge.tsx b/packages/website/src/components/ui/badge.tsx
new file mode 100644
index 0000000..4072656
--- /dev/null
+++ b/packages/website/src/components/ui/badge.tsx
@@ -0,0 +1,37 @@
+import { Slot } from '@radix-ui/react-slot'
+import { type VariantProps, cva } from 'class-variance-authority'
+import * as React from 'react'
+
+import { cn } from '@/lib/utils'
+
+const badgeVariants = cva(
+	'inline-flex items-center justify-center rounded-full border px-2 py-0.5 text-xs font-medium w-fit whitespace-nowrap shrink-0 [&>svg]:size-3 gap-1 [&>svg]:pointer-events-none focus-visible:border-ring focus-visible:ring-ring/50 focus-visible:ring-[3px] aria-invalid:ring-destructive/20 dark:aria-invalid:ring-destructive/40 aria-invalid:border-destructive transition-[color,box-shadow] overflow-hidden',
+	{
+		variants: {
+			variant: {
+				default: 'border-transparent bg-primary text-primary-foreground [a&]:hover:bg-primary/90',
+				secondary:
+					'border-transparent bg-secondary text-secondary-foreground [a&]:hover:bg-secondary/90',
+				destructive:
+					'border-transparent bg-destructive text-white [a&]:hover:bg-destructive/90 focus-visible:ring-destructive/20 dark:focus-visible:ring-destructive/40 dark:bg-destructive/60',
+				outline: 'text-foreground [a&]:hover:bg-accent [a&]:hover:text-accent-foreground',
+			},
+		},
+		defaultVariants: {
+			variant: 'default',
+		},
+	}
+)
+
+function Badge({
+	className,
+	variant,
+	asChild = false,
+	...props
+}: React.ComponentProps<'span'> & VariantProps<typeof badgeVariants> & { asChild?: boolean }) {
+	const Comp = asChild ? Slot : 'span'
+
+	return <Comp data-slot="badge" className={cn(badgeVariants({ variant }), className)} {...props} />
+}
+
+export { Badge, badgeVariants }
diff --git a/packages/website/src/components/ui/bento-grid.tsx b/packages/website/src/components/ui/bento-grid.tsx
new file mode 100644
index 0000000..9289074
--- /dev/null
+++ b/packages/website/src/components/ui/bento-grid.tsx
@@ -0,0 +1,91 @@
+import { ArrowRightIcon } from '@radix-ui/react-icons'
+import { ComponentPropsWithoutRef, ReactNode } from 'react'
+
+import { Button } from '@/components/ui/button'
+import { cn } from '@/lib/utils'
+
+interface BentoGridProps extends ComponentPropsWithoutRef<'div'> {
+	children: ReactNode
+	className?: string
+}
+
+interface BentoCardProps extends ComponentPropsWithoutRef<'div'> {
+	name: string
+	className: string
+	background: ReactNode
+	Icon: React.ElementType
+	description: string
+	href: string
+	cta: string
+}
+
+const BentoGrid = ({ children, className, ...props }: BentoGridProps) => {
+	return (
+		<div className={cn('grid w-full auto-rows-[22rem] grid-cols-3 gap-4', className)} {...props}>
+			{children}
+		</div>
+	)
+}
+
+const BentoCard = ({
+	name,
+	className,
+	background,
+	Icon,
+	description,
+	href,
+	cta,
+	...props
+}: BentoCardProps) => (
+	<div
+		key={name}
+		className={cn(
+			'group relative col-span-3 flex flex-col justify-between overflow-hidden rounded-xl',
+			// light styles
+			'bg-background [box-shadow:0_0_0_1px_rgba(0,0,0,.03),0_2px_4px_rgba(0,0,0,.05),0_12px_24px_rgba(0,0,0,.05)]',
+			// dark styles
+			'dark:bg-background transform-gpu dark:[box-shadow:0_-20px_80px_-20px_#ffffff1f_inset] dark:[border:1px_solid_rgba(255,255,255,.1)]',
+			className
+		)}
+		{...props}
+	>
+		<div>{background}</div>
+		<div className="p-4">
+			<div className="pointer-events-none z-10 flex transform-gpu flex-col gap-1 transition-all duration-300 lg:group-hover:-translate-y-10">
+				<Icon className="h-12 w-12 origin-left transform-gpu text-neutral-700 transition-all duration-300 ease-in-out group-hover:scale-75" />
+				<h3 className="text-xl font-semibold text-neutral-700 dark:text-neutral-300">{name}</h3>
+				<p className="max-w-lg text-neutral-400">{description}</p>
+			</div>
+
+			<div
+				className={cn(
+					'pointer-events-none flex w-full translate-y-0 transform-gpu flex-row items-center transition-all duration-300 group-hover:translate-y-0 group-hover:opacity-100 lg:hidden'
+				)}
+			>
+				<Button variant="link" asChild size="sm" className="pointer-events-auto p-0">
+					<a href={href}>
+						{cta}
+						<ArrowRightIcon className="ms-2 h-4 w-4 rtl:rotate-180" />
+					</a>
+				</Button>
+			</div>
+		</div>
+
+		<div
+			className={cn(
+				'pointer-events-none absolute bottom-0 hidden w-full translate-y-10 transform-gpu flex-row items-center p-4 opacity-0 transition-all duration-300 group-hover:translate-y-0 group-hover:opacity-100 lg:flex'
+			)}
+		>
+			<Button variant="link" asChild size="sm" className="pointer-events-auto p-0">
+				<a href={href}>
+					{cta}
+					<ArrowRightIcon className="ms-2 h-4 w-4 rtl:rotate-180" />
+				</a>
+			</Button>
+		</div>
+
+		<div className="pointer-events-none absolute inset-0 transform-gpu transition-all duration-300 group-hover:bg-black/[.03] group-hover:dark:bg-neutral-800/10" />
+	</div>
+)
+
+export { BentoCard, BentoGrid }
diff --git a/packages/website/src/components/ui/blur-fade.tsx b/packages/website/src/components/ui/blur-fade.tsx
new file mode 100644
index 0000000..13d109f
--- /dev/null
+++ b/packages/website/src/components/ui/blur-fade.tsx
@@ -0,0 +1,79 @@
+import {
+	AnimatePresence,
+	MotionProps,
+	UseInViewOptions,
+	Variants,
+	motion,
+	useInView,
+} from 'motion/react'
+import { useRef } from 'react'
+
+type MarginType = UseInViewOptions['margin']
+
+interface BlurFadeProps extends MotionProps {
+	children: React.ReactNode
+	className?: string
+	variant?: {
+		hidden: { y: number }
+		visible: { y: number }
+	}
+	duration?: number
+	delay?: number
+	offset?: number
+	direction?: 'up' | 'down' | 'left' | 'right'
+	inView?: boolean
+	inViewMargin?: MarginType
+	blur?: string
+}
+
+export function BlurFade({
+	children,
+	className,
+	variant,
+	duration = 0.4,
+	delay = 0,
+	offset = 6,
+	direction = 'down',
+	inView = false,
+	inViewMargin = '-50px',
+	blur = '6px',
+	...props
+}: BlurFadeProps) {
+	const ref = useRef(null)
+	const inViewResult = useInView(ref, { once: true, margin: inViewMargin })
+	const isInView = !inView || inViewResult
+	const defaultVariants: Variants = {
+		hidden: {
+			[direction === 'left' || direction === 'right' ? 'x' : 'y']:
+				direction === 'right' || direction === 'down' ? -offset : offset,
+			opacity: 0,
+			filter: `blur(${blur})`,
+		},
+		visible: {
+			[direction === 'left' || direction === 'right' ? 'x' : 'y']: 0,
+			opacity: 1,
+			filter: `blur(0px)`,
+		},
+	}
+	const combinedVariants = variant || defaultVariants
+	return (
+		<AnimatePresence>
+			<motion.div
+				ref={ref}
+				initial="hidden"
+				animate={isInView ? 'visible' : 'hidden'}
+				exit="hidden"
+				variants={combinedVariants}
+				transition={{
+					delay: 0.04 + delay,
+					duration,
+					ease: 'easeOut',
+				}}
+				className={className}
+				{...props}
+			>
+				{children}
+			</motion.div>
+		</AnimatePresence>
+	)
+}
diff --git a/packages/website/src/components/ui/button.tsx b/packages/website/src/components/ui/button.tsx
new file mode 100644
index 0000000..3579cbd
--- /dev/null
+++ b/packages/website/src/components/ui/button.tsx
@@ -0,0 +1,60 @@
+import { Slot } from '@radix-ui/react-slot'
+import { type VariantProps, cva } from 'class-variance-authority'
+import * as React from 'react'
+
+import { cn } from '@/lib/utils'
+
+const buttonVariants = cva(
+	"inline-flex items-center justify-center gap-2 whitespace-nowrap rounded-md text-sm font-medium transition-all disabled:pointer-events-none disabled:opacity-50 [&_svg]:pointer-events-none [&_svg:not([class*='size-'])]:size-4 shrink-0 [&_svg]:shrink-0 outline-none focus-visible:border-ring focus-visible:ring-ring/50 focus-visible:ring-[3px] aria-invalid:ring-destructive/20 dark:aria-invalid:ring-destructive/40 aria-invalid:border-destructive",
+	{
+		variants: {
+			variant: {
+				default: 'bg-primary text-primary-foreground hover:bg-primary/90',
+				destructive:
+					'bg-destructive text-white hover:bg-destructive/90 focus-visible:ring-destructive/20 dark:focus-visible:ring-destructive/40 dark:bg-destructive/60',
+				outline:
+					'border bg-background shadow-xs hover:bg-accent hover:text-accent-foreground dark:bg-input/30 dark:border-input dark:hover:bg-input/50',
+				secondary: 'bg-secondary text-secondary-foreground hover:bg-secondary/80',
+				ghost: 'hover:bg-accent hover:text-accent-foreground dark:hover:bg-accent/50',
+				link: 'text-primary underline-offset-4 hover:underline',
+			},
+			size: {
+				default: 'h-9 px-4 py-2 has-[>svg]:px-3',
+				sm: 'h-8 rounded-md gap-1.5 px-3 has-[>svg]:px-2.5',
+				lg: 'h-10 rounded-md px-6 has-[>svg]:px-4',
+				icon: 'size-9',
+				'icon-sm': 'size-8',
+				'icon-lg': 'size-10',
+			},
+		},
+		defaultVariants: {
+			variant: 'default',
+			size: 'default',
+		},
+	}
+)
+
+function Button({
+	className,
+	variant = 'default',
+	size = 'default',
+	asChild = false,
+	...props
+}: React.ComponentProps<'button'> &
+	VariantProps<typeof buttonVariants> & {
+		asChild?: boolean
+	}) {
+	const Comp = asChild ? Slot : 'button'
+
+	return (
+		<Comp
+			data-slot="button"
+			data-variant={variant}
+			data-size={size}
+			className={cn(buttonVariants({ variant, size, className }))}
+			{...props}
+		/>
+	)
+}
+
+export { Button, buttonVariants }
diff --git a/packages/website/src/components/ui/highlighter.tsx b/packages/website/src/components/ui/highlighter.tsx
new file mode 100644
index 0000000..b0651f5
--- /dev/null
+++ b/packages/website/src/components/ui/highlighter.tsx
@@ -0,0 +1,92 @@
+import { useInView } from 'motion/react'
+import { useEffect, useRef } from 'react'
+import type React from 'react'
+import { annotate } from 'rough-notation'
+import { type RoughAnnotation } from 'rough-notation/lib/model'
+
+type AnnotationAction =
+	| 'highlight'
+	| 'underline'
+	| 'box'
+	| 'circle'
+	| 'strike-through'
+	| 'crossed-off'
+	| 'bracket'
+
+interface HighlighterProps {
+	children: React.ReactNode
+	action?: AnnotationAction
+	color?: string
+	strokeWidth?: number
+	animationDuration?: number
+	iterations?: number
+	padding?: number
+	multiline?: boolean
+	isView?: boolean
+}
+
+export function Highlighter({
+	children,
+	action = 'highlight',
+	color = '#ffd1dc',
+	strokeWidth = 1.5,
+	animationDuration = 600,
+	iterations = 2,
+	padding = 2,
+	multiline = true,
+	isView = false,
+}: HighlighterProps) {
+	const elementRef = useRef<HTMLSpanElement>(null)
+	const annotationRef = useRef<RoughAnnotation | null>(null)
+
+	const isInView = useInView(elementRef, {
+		once: true,
+		margin: '-10%',
+	})
+
+	// If isView is false, always show. If isView is true, wait for inView
+	const shouldShow = !isView || isInView
+
+	useEffect(() => {
+		if (!shouldShow) return
+
+		const element = elementRef.current
+		if (!element) return
+
+		const annotationConfig = {
+			type: action,
+			color,
+			strokeWidth,
+			animationDuration,
+			iterations,
+			padding,
+			multiline,
+		}
+
+		const annotation = annotate(element, annotationConfig)
+
+		annotationRef.current = annotation
+		annotationRef.current.show()
+
+		const resizeObserver = new ResizeObserver(() => {
+			annotation.hide()
+			annotation.show()
+		})
+
+		resizeObserver.observe(element)
+		resizeObserver.observe(document.body)
+
+		return () => {
+			if (element) {
+				annotate(element, { type: action }).remove()
+				resizeObserver.disconnect()
+			}
+		}
+	}, [shouldShow, action, color, strokeWidth, animationDuration, iterations, padding, multiline])
+
+	return (
+		<span ref={elementRef} className="relative inline-block bg-transparent">
+			{children}
+		</span>
+	)
+}
diff --git a/packages/website/src/components/ui/hyper-text.tsx b/packages/website/src/components/ui/hyper-text.tsx
new file mode 100644
index 0000000..10cf166
--- /dev/null
+++ b/packages/website/src/components/ui/hyper-text.tsx
@@ -0,0 +1,140 @@
+import { AnimatePresence, MotionProps, motion } from 'motion/react'
+import { useEffect, useRef, useState } from 'react'
+
+import { cn } from '@/lib/utils'
+
+type CharacterSet = string[] | readonly string[]
+
+interface HyperTextProps extends MotionProps {
+	/** The text content to be animated */
+	children: string
+	/** Optional className for styling */
+	className?: string
+	/** Duration of the animation in milliseconds */
+	duration?: number
+	/** Delay before animation starts in milliseconds */
+	delay?: number
+	/** Component to render as - defaults to div */
+	as?: React.ElementType
+	/** Whether to start animation when element comes into view */
+	startOnView?: boolean
+	/** Whether to trigger animation on hover */
+	animateOnHover?: boolean
+	/** Custom character set for scramble effect. Defaults to uppercase alphabet */
+	characterSet?: CharacterSet
+}
+
+const DEFAULT_CHARACTER_SET = Object.freeze(
+	'ABCDEFGHIJKLMNOPQRSTUVWXYZ'.split('')
+) as readonly string[]
+
+const getRandomInt = (max: number): number => Math.floor(Math.random() * max)
+
+export function HyperText({
+	children,
+	className,
+	duration = 800,
+	delay = 0,
+	as: Component = 'div',
+	startOnView = false,
+	animateOnHover = true,
+	characterSet = DEFAULT_CHARACTER_SET,
+	...props
+}: HyperTextProps) {
+	const MotionComponent = motion.create(Component, {
+		forwardMotionProps: true,
+	})
+
+	const [displayText, setDisplayText] = useState<string[]>(() => children.split(''))
+	const [isAnimating, setIsAnimating] = useState(false)
+	const iterationCount = useRef(0)
+	const elementRef = useRef<HTMLElement>(null)
+
+	const handleAnimationTrigger = () => {
+		if (animateOnHover && !isAnimating) {
+			iterationCount.current = 0
+			setIsAnimating(true)
+		}
+	}
+
+	// Handle animation start based on view or delay
+	useEffect(() => {
+		if (!startOnView) {
+			const startTimeout = setTimeout(() => {
+				setIsAnimating(true)
+			}, delay)
+			return () => clearTimeout(startTimeout)
+		}
+
+		const observer = new IntersectionObserver(
+			([entry]) => {
+				if (entry.isIntersecting) {
+					setTimeout(() => {
+						setIsAnimating(true)
+					}, delay)
+					observer.disconnect()
+				}
+			},
+			{ threshold: 0.1, rootMargin: '-30% 0px -30% 0px' }
+		)
+
+		if (elementRef.current) {
+			observer.observe(elementRef.current)
+		}
+
+		return () => observer.disconnect()
+	}, [delay, startOnView])
+
+	// Handle scramble animation
+	useEffect(() => {
+		if (!isAnimating) return
+
+		const maxIterations = children.length
+		const startTime = performance.now()
+		let animationFrameId: number
+
+		const animate = (currentTime: number) => {
+			const elapsed = currentTime - startTime
+			const progress = Math.min(elapsed / duration, 1)
+
+			iterationCount.current = progress * maxIterations
+
+			setDisplayText((currentText) =>
+				currentText.map((letter, index) =>
+					letter === ' '
+						? letter
+						: index <= iterationCount.current
+							? children[index]
+							: characterSet[getRandomInt(characterSet.length)]
+				)
+			)
+
+			if (progress < 1) {
+				animationFrameId = requestAnimationFrame(animate)
+			} else {
+				setIsAnimating(false)
+			}
+		}
+
+		animationFrameId = requestAnimationFrame(animate)
+
+		return () => cancelAnimationFrame(animationFrameId)
+	}, [children, duration, isAnimating, characterSet])
+
+	return (
+		<MotionComponent
+			ref={elementRef}
+			className={cn('overflow-hidden py-2 text-4xl font-bold', className)}
+			onMouseEnter={handleAnimationTrigger}
+			{...props}
+		>
+			<AnimatePresence>
+				{displayText.map((letter, index) => (
+					<motion.span key={index} className={cn('font-mono', letter === ' ' ? 'w-3' : '')}>
+						{letter.toUpperCase()}
+					</motion.span>
+				))}
+			</AnimatePresence>
+		</MotionComponent>
+	)
+}
diff --git a/packages/website/src/components/ui/kbd.tsx b/packages/website/src/components/ui/kbd.tsx
new file mode 100644
index 0000000..b5468bd
--- /dev/null
+++ b/packages/website/src/components/ui/kbd.tsx
@@ -0,0 +1,28 @@
+import { cn } from '@/lib/utils'
+
+function Kbd({ className, ...props }: React.ComponentProps<'kbd'>) {
+	return (
+		<kbd
+			data-slot="kbd"
+			className={cn(
+				'bg-muted text-muted-foreground pointer-events-none inline-flex h-5 w-fit min-w-5 items-center justify-center gap-1 rounded-sm px-1 font-sans text-xs font-medium select-none',
+				"[&_svg:not([class*='size-'])]:size-3",
+				'[[data-slot=tooltip-content]_&]:bg-background/20 [[data-slot=tooltip-content]_&]:text-background dark:[[data-slot=tooltip-content]_&]:bg-background/10',
+				className
+			)}
+			{...props}
+		/>
+	)
+}
+
+function KbdGroup({ className, ...props }: React.ComponentProps<'div'>) {
+	return (
+		<kbd
+			data-slot="kbd-group"
+			className={cn('inline-flex items-center gap-1', className)}
+			{...props}
+		/>
+	)
+}
+
+export { Kbd, KbdGroup }
diff --git a/packages/website/src/components/ui/magic-card.tsx b/packages/website/src/components/ui/magic-card.tsx
new file mode 100644
index 0000000..d040937
--- /dev/null
+++ b/packages/website/src/components/ui/magic-card.tsx
@@ -0,0 +1,101 @@
+import { motion, useMotionTemplate, useMotionValue } from 'motion/react'
+import React, { useCallback, useEffect } from 'react'
+
+import { cn } from '@/lib/utils'
+
+interface MagicCardProps {
+	children?: React.ReactNode
+	className?: string
+	gradientSize?: number
+	gradientColor?: string
+	gradientOpacity?: number
+	gradientFrom?: string
+	gradientTo?: string
+}
+
+export function MagicCard({
+	children,
+	className,
+	gradientSize = 200,
+	gradientColor = '#262626',
+	gradientOpacity = 0.8,
+	gradientFrom = '#9E7AFF',
+	gradientTo = '#FE8BBB',
+}: MagicCardProps) {
+	const mouseX = useMotionValue(-gradientSize)
+	const mouseY = useMotionValue(-gradientSize)
+	const reset = useCallback(() => {
+		mouseX.set(-gradientSize)
+		mouseY.set(-gradientSize)
+	}, [gradientSize, mouseX, mouseY])
+
+	const handlePointerMove = useCallback(
+		(e: React.PointerEvent<HTMLDivElement>) => {
+			const rect = e.currentTarget.getBoundingClientRect()
+			mouseX.set(e.clientX - rect.left)
+			mouseY.set(e.clientY - rect.top)
+		},
+		[mouseX, mouseY]
+	)
+
+	useEffect(() => {
+		reset()
+	}, [reset])
+
+	useEffect(() => {
+		const handleGlobalPointerOut = (e: PointerEvent) => {
+			if (!e.relatedTarget) {
+				reset()
+			}
+		}
+
+		const handleVisibility = () => {
+			if (document.visibilityState !== 'visible') {
+				reset()
+			}
+		}
+
+		window.addEventListener('pointerout', handleGlobalPointerOut)
+		window.addEventListener('blur', reset)
+		document.addEventListener('visibilitychange', handleVisibility)
+
+		return () => {
+			window.removeEventListener('pointerout', handleGlobalPointerOut)
+			window.removeEventListener('blur', reset)
+			document.removeEventListener('visibilitychange', handleVisibility)
+		}
+	}, [reset])
+
+	return (
+		<div
+			className={cn('group relative rounded-[inherit]', className)}
+			onPointerMove={handlePointerMove}
+			onPointerLeave={reset}
+			onPointerEnter={reset}
+		>
+			<motion.div
+				className="bg-border pointer-events-none absolute inset-0 rounded-[inherit] duration-300 group-hover:opacity-100"
+				style={{
+					background: useMotionTemplate`
+          radial-gradient(${gradientSize}px circle at ${mouseX}px ${mouseY}px,
+          ${gradientFrom}, 
+          ${gradientTo}, 
+          var(--border) 100%
+          )
+          `,
+				}}
+			/>
+			<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={{
+					background: useMotionTemplate`
+            radial-gradient(${gradientSize}px circle at ${mouseX}px ${mouseY}px, ${gradientColor}, transparent 100%)
+          `,
+					opacity: gradientOpacity,
+				}}
+			/>
+			<div className="relative">{children}</div>
+		</div>
+	)
+}
diff --git a/packages/website/src/components/ui/marquee.tsx b/packages/website/src/components/ui/marquee.tsx
new file mode 100644
index 0000000..75027d0
--- /dev/null
+++ b/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>
+	)
+}
diff --git a/packages/website/src/components/ui/neon-gradient-card.tsx b/packages/website/src/components/ui/neon-gradient-card.tsx
new file mode 100644
index 0000000..b372761
--- /dev/null
+++ b/packages/website/src/components/ui/neon-gradient-card.tsx
@@ -0,0 +1,136 @@
+import { CSSProperties, ReactElement, ReactNode, useEffect, useRef, useState } from 'react'
+
+import { cn } from '@/lib/utils'
+
+interface NeonColorsProps {
+	firstColor: string
+	secondColor: string
+}
+
+interface NeonGradientCardProps extends React.HTMLAttributes<HTMLDivElement> {
+	/**
+	 * @default <div />
+	 * @type ReactElement
+	 * @description
+	 * The component to be rendered as the card
+	 * */
+	as?: ReactElement
+	/**
+	 * @default ""
+	 * @type string
+	 * @description
+	 * The className of the card
+	 */
+	className?: string
+
+	/**
+	 * @default ""
+	 * @type ReactNode
+	 * @description
+	 * The children of the card
+	 * */
+	children?: ReactNode
+
+	/**
+	 * @default 5
+	 * @type number
+	 * @description
+	 * The size of the border in pixels
+	 * */
+	borderSize?: number
+
+	/**
+	 * @default 20
+	 * @type number
+	 * @description
+	 * The size of the radius in pixels
+	 * */
+	borderRadius?: number
+
+	/**
+	 * @default "{ firstColor: '#ff00aa', secondColor: '#00FFF1' }"
+	 * @type string
+	 * @description
+	 * The colors of the neon gradient
+	 * */
+	neonColors?: NeonColorsProps
+}
+
+export const NeonGradientCard: React.FC<NeonGradientCardProps> = ({
+	className,
+	children,
+	borderSize = 2,
+	borderRadius = 20,
+	neonColors = {
+		firstColor: '#ff00aa',
+		secondColor: '#00FFF1',
+	},
+	...props
+}) => {
+	const containerRef = useRef<HTMLDivElement>(null)
+	const [dimensions, setDimensions] = useState({ width: 0, height: 0 })
+
+	useEffect(() => {
+		const updateDimensions = () => {
+			if (containerRef.current) {
+				const { offsetWidth, offsetHeight } = containerRef.current
+				setDimensions({ width: offsetWidth, height: offsetHeight })
+			}
+		}
+
+		updateDimensions()
+		window.addEventListener('resize', updateDimensions)
+
+		return () => {
+			window.removeEventListener('resize', updateDimensions)
+		}
+	}, [])
+
+	useEffect(() => {
+		if (containerRef.current) {
+			const { offsetWidth, offsetHeight } = containerRef.current
+			setDimensions({ width: offsetWidth, height: offsetHeight })
+		}
+	}, [children])
+
+	return (
+		<div
+			ref={containerRef}
+			style={
+				{
+					'--border-size': `${borderSize}px`,
+					'--border-radius': `${borderRadius}px`,
+					'--neon-first-color': neonColors.firstColor,
+					'--neon-second-color': neonColors.secondColor,
+					'--card-width': `${dimensions.width}px`,
+					'--card-height': `${dimensions.height}px`,
+					'--card-content-radius': `${borderRadius - borderSize}px`,
+					'--pseudo-element-background-image': `linear-gradient(0deg, ${neonColors.firstColor}, ${neonColors.secondColor})`,
+					'--pseudo-element-width': `${dimensions.width + borderSize * 2}px`,
+					'--pseudo-element-height': `${dimensions.height + borderSize * 2}px`,
+					'--after-blur': `${dimensions.width / 6}px`,
+				} as CSSProperties
+			}
+			className={cn('relative z-10 size-full rounded-[var(--border-radius)]', className)}
+			{...props}
+		>
+			<div
+				className={cn(
+					'relative size-full min-h-[inherit] rounded-[var(--card-content-radius)] bg-gray-100',
+					'before:absolute before:-top-[var(--border-size)] before:-left-[var(--border-size)] before:-z-10 before:block',
+					"before:h-[var(--pseudo-element-height)] before:w-[var(--pseudo-element-width)] before:rounded-[var(--border-radius)] before:content-['']",
+					'before:bg-[linear-gradient(0deg,var(--neon-first-color),var(--neon-second-color))] before:bg-[length:100%_200%]',
+					'before:animate-background-position-spin',
+					'after:absolute after:-top-[var(--border-size)] after:-left-[var(--border-size)] after:-z-10 after:block',
+					"after:h-[var(--pseudo-element-height)] after:w-[var(--pseudo-element-width)] after:rounded-[var(--border-radius)] after:blur-[var(--after-blur)] after:content-['']",
+					'after:bg-[linear-gradient(0deg,var(--neon-first-color),var(--neon-second-color))] after:bg-[length:100%_200%] after:opacity-80',
+					'after:animate-background-position-spin',
+					'dark:bg-neutral-900',
+					'break-words'
+				)}
+			>
+				{children}
+			</div>
+		</div>
+	)
+}
diff --git a/packages/website/src/components/ui/particles.tsx b/packages/website/src/components/ui/particles.tsx
new file mode 100644
index 0000000..9a13df6
--- /dev/null
+++ b/packages/website/src/components/ui/particles.tsx
@@ -0,0 +1,297 @@
+import React, { ComponentPropsWithoutRef, useEffect, useRef, useState } from 'react'
+
+import { cn } from '@/lib/utils'
+
+interface MousePosition {
+	x: number
+	y: number
+}
+
+function MousePosition(): MousePosition {
+	const [mousePosition, setMousePosition] = useState<MousePosition>({
+		x: 0,
+		y: 0,
+	})
+
+	useEffect(() => {
+		const handleMouseMove = (event: MouseEvent) => {
+			setMousePosition({ x: event.clientX, y: event.clientY })
+		}
+
+		window.addEventListener('mousemove', handleMouseMove)
+
+		return () => {
+			window.removeEventListener('mousemove', handleMouseMove)
+		}
+	}, [])
+
+	return mousePosition
+}
+
+interface ParticlesProps extends ComponentPropsWithoutRef<'div'> {
+	className?: string
+	quantity?: number
+	staticity?: number
+	ease?: number
+	size?: number
+	refresh?: boolean
+	color?: string
+	vx?: number
+	vy?: number
+}
+
+function hexToRgb(hex: string): number[] {
+	hex = hex.replace('#', '')
+
+	if (hex.length === 3) {
+		hex = hex
+			.split('')
+			.map((char) => char + char)
+			.join('')
+	}
+
+	const hexInt = parseInt(hex, 16)
+	const red = (hexInt >> 16) & 255
+	const green = (hexInt >> 8) & 255
+	const blue = hexInt & 255
+	return [red, green, blue]
+}
+
+type Circle = {
+	x: number
+	y: number
+	translateX: number
+	translateY: number
+	size: number
+	alpha: number
+	targetAlpha: number
+	dx: number
+	dy: number
+	magnetism: number
+}
+
+export const Particles: React.FC<ParticlesProps> = ({
+	className = '',
+	quantity = 100,
+	staticity = 50,
+	ease = 50,
+	size = 0.4,
+	refresh = false,
+	color = '#ffffff',
+	vx = 0,
+	vy = 0,
+	...props
+}) => {
+	const canvasRef = useRef<HTMLCanvasElement>(null)
+	const canvasContainerRef = useRef<HTMLDivElement>(null)
+	const context = useRef<CanvasRenderingContext2D | null>(null)
+	const circles = useRef<Circle[]>([])
+	const mousePosition = MousePosition()
+	const mouse = useRef<{ x: number; y: number }>({ x: 0, y: 0 })
+	const canvasSize = useRef<{ w: number; h: number }>({ w: 0, h: 0 })
+	const dpr = typeof window !== 'undefined' ? window.devicePixelRatio : 1
+	const rafID = useRef<number | null>(null)
+	const resizeTimeout = useRef<NodeJS.Timeout | null>(null)
+
+	useEffect(() => {
+		if (canvasRef.current) {
+			context.current = canvasRef.current.getContext('2d')
+		}
+		initCanvas()
+		animate()
+
+		const handleResize = () => {
+			if (resizeTimeout.current) {
+				clearTimeout(resizeTimeout.current)
+			}
+			resizeTimeout.current = setTimeout(() => {
+				initCanvas()
+			}, 200)
+		}
+
+		window.addEventListener('resize', handleResize)
+
+		return () => {
+			if (rafID.current != null) {
+				window.cancelAnimationFrame(rafID.current)
+			}
+			if (resizeTimeout.current) {
+				clearTimeout(resizeTimeout.current)
+			}
+			window.removeEventListener('resize', handleResize)
+		}
+	}, [color])
+
+	useEffect(() => {
+		onMouseMove()
+	}, [mousePosition.x, mousePosition.y])
+
+	useEffect(() => {
+		initCanvas()
+	}, [refresh])
+
+	const initCanvas = () => {
+		resizeCanvas()
+		drawParticles()
+	}
+
+	const onMouseMove = () => {
+		if (canvasRef.current) {
+			const rect = canvasRef.current.getBoundingClientRect()
+			const { w, h } = canvasSize.current
+			const x = mousePosition.x - rect.left - w / 2
+			const y = mousePosition.y - rect.top - h / 2
+			const inside = x < w / 2 && x > -w / 2 && y < h / 2 && y > -h / 2
+			if (inside) {
+				mouse.current.x = x
+				mouse.current.y = y
+			}
+		}
+	}
+
+	const resizeCanvas = () => {
+		if (canvasContainerRef.current && canvasRef.current && context.current) {
+			canvasSize.current.w = canvasContainerRef.current.offsetWidth
+			canvasSize.current.h = canvasContainerRef.current.offsetHeight
+
+			canvasRef.current.width = canvasSize.current.w * dpr
+			canvasRef.current.height = canvasSize.current.h * dpr
+			canvasRef.current.style.width = `${canvasSize.current.w}px`
+			canvasRef.current.style.height = `${canvasSize.current.h}px`
+			context.current.scale(dpr, dpr)
+
+			// Clear existing particles and create new ones with exact quantity
+			circles.current = []
+			for (let i = 0; i < quantity; i++) {
+				const circle = circleParams()
+				drawCircle(circle)
+			}
+		}
+	}
+
+	const circleParams = (): Circle => {
+		const x = Math.floor(Math.random() * canvasSize.current.w)
+		const y = Math.floor(Math.random() * canvasSize.current.h)
+		const translateX = 0
+		const translateY = 0
+		const pSize = Math.floor(Math.random() * 2) + size
+		const alpha = 0
+		const targetAlpha = parseFloat((Math.random() * 0.6 + 0.1).toFixed(1))
+		const dx = (Math.random() - 0.5) * 0.1
+		const dy = (Math.random() - 0.5) * 0.1
+		const magnetism = 0.1 + Math.random() * 4
+		return {
+			x,
+			y,
+			translateX,
+			translateY,
+			size: pSize,
+			alpha,
+			targetAlpha,
+			dx,
+			dy,
+			magnetism,
+		}
+	}
+
+	const rgb = hexToRgb(color)
+
+	const drawCircle = (circle: Circle, update = false) => {
+		if (context.current) {
+			const { x, y, translateX, translateY, size, alpha } = circle
+			context.current.translate(translateX, translateY)
+			context.current.beginPath()
+			context.current.arc(x, y, size, 0, 2 * Math.PI)
+			context.current.fillStyle = `rgba(${rgb.join(', ')}, ${alpha})`
+			context.current.fill()
+			context.current.setTransform(dpr, 0, 0, dpr, 0, 0)
+
+			if (!update) {
+				circles.current.push(circle)
+			}
+		}
+	}
+
+	const clearContext = () => {
+		if (context.current) {
+			context.current.clearRect(0, 0, canvasSize.current.w, canvasSize.current.h)
+		}
+	}
+
+	const drawParticles = () => {
+		clearContext()
+		const particleCount = quantity
+		for (let i = 0; i < particleCount; i++) {
+			const circle = circleParams()
+			drawCircle(circle)
+		}
+	}
+
+	const remapValue = (
+		value: number,
+		start1: number,
+		end1: number,
+		start2: number,
+		end2: number
+	): number => {
+		const remapped = ((value - start1) * (end2 - start2)) / (end1 - start1) + start2
+		return remapped > 0 ? remapped : 0
+	}
+
+	const animate = () => {
+		clearContext()
+		circles.current.forEach((circle: Circle, i: number) => {
+			// Handle the alpha value
+			const edge = [
+				circle.x + circle.translateX - circle.size, // distance from left edge
+				canvasSize.current.w - circle.x - circle.translateX - circle.size, // distance from right edge
+				circle.y + circle.translateY - circle.size, // distance from top edge
+				canvasSize.current.h - circle.y - circle.translateY - circle.size, // distance from bottom edge
+			]
+			const closestEdge = edge.reduce((a, b) => Math.min(a, b))
+			const remapClosestEdge = parseFloat(remapValue(closestEdge, 0, 20, 0, 1).toFixed(2))
+			if (remapClosestEdge > 1) {
+				circle.alpha += 0.02
+				if (circle.alpha > circle.targetAlpha) {
+					circle.alpha = circle.targetAlpha
+				}
+			} else {
+				circle.alpha = circle.targetAlpha * remapClosestEdge
+			}
+			circle.x += circle.dx + vx
+			circle.y += circle.dy + vy
+			circle.translateX +=
+				(mouse.current.x / (staticity / circle.magnetism) - circle.translateX) / ease
+			circle.translateY +=
+				(mouse.current.y / (staticity / circle.magnetism) - circle.translateY) / ease
+
+			drawCircle(circle, true)
+
+			// circle gets out of the canvas
+			if (
+				circle.x < -circle.size ||
+				circle.x > canvasSize.current.w + circle.size ||
+				circle.y < -circle.size ||
+				circle.y > canvasSize.current.h + circle.size
+			) {
+				// remove the circle from the array
+				circles.current.splice(i, 1)
+				// create a new circle
+				const newCircle = circleParams()
+				drawCircle(newCircle)
+			}
+		})
+		rafID.current = window.requestAnimationFrame(animate)
+	}
+
+	return (
+		<div
+			className={cn('pointer-events-none', className)}
+			ref={canvasContainerRef}
+			aria-hidden="true"
+			{...props}
+		>
+			<canvas ref={canvasRef} className="size-full" />
+		</div>
+	)
+}
diff --git a/packages/website/src/components/ui/separator.tsx b/packages/website/src/components/ui/separator.tsx
new file mode 100644
index 0000000..ae51953
--- /dev/null
+++ b/packages/website/src/components/ui/separator.tsx
@@ -0,0 +1,26 @@
+import * as SeparatorPrimitive from '@radix-ui/react-separator'
+import * as React from 'react'
+
+import { cn } from '@/lib/utils'
+
+function Separator({
+	className,
+	orientation = 'horizontal',
+	decorative = true,
+	...props
+}: React.ComponentProps<typeof SeparatorPrimitive.Root>) {
+	return (
+		<SeparatorPrimitive.Root
+			data-slot="separator"
+			decorative={decorative}
+			orientation={orientation}
+			className={cn(
+				'bg-border shrink-0 data-[orientation=horizontal]:h-px data-[orientation=horizontal]:w-full data-[orientation=vertical]:h-full data-[orientation=vertical]:w-px',
+				className
+			)}
+			{...props}
+		/>
+	)
+}
+
+export { Separator }
diff --git a/packages/website/src/components/ui/sonner.tsx b/packages/website/src/components/ui/sonner.tsx
new file mode 100644
index 0000000..21835dc
--- /dev/null
+++ b/packages/website/src/components/ui/sonner.tsx
@@ -0,0 +1,38 @@
+import {
+	CircleCheckIcon,
+	InfoIcon,
+	Loader2Icon,
+	OctagonXIcon,
+	TriangleAlertIcon,
+} from 'lucide-react'
+import { useTheme } from 'next-themes'
+import { Toaster as Sonner, type ToasterProps } from 'sonner'
+
+const Toaster = ({ ...props }: ToasterProps) => {
+	const { theme = 'system' } = useTheme()
+
+	return (
+		<Sonner
+			theme={theme as ToasterProps['theme']}
+			className="toaster group"
+			icons={{
+				success: <CircleCheckIcon className="size-4" />,
+				info: <InfoIcon className="size-4" />,
+				warning: <TriangleAlertIcon className="size-4" />,
+				error: <OctagonXIcon className="size-4" />,
+				loading: <Loader2Icon className="size-4 animate-spin" />,
+			}}
+			style={
+				{
+					'--normal-bg': 'var(--popover)',
+					'--normal-text': 'var(--popover-foreground)',
+					'--normal-border': 'var(--border)',
+					'--border-radius': 'var(--radius)',
+				} as React.CSSProperties
+			}
+			{...props}
+		/>
+	)
+}
+
+export { Toaster }
diff --git a/packages/website/src/components/ui/sparkles-text.tsx b/packages/website/src/components/ui/sparkles-text.tsx
new file mode 100644
index 0000000..ad31fb8
--- /dev/null
+++ b/packages/website/src/components/ui/sparkles-text.tsx
@@ -0,0 +1,150 @@
+import { motion } from 'motion/react'
+import { CSSProperties, ReactElement, useEffect, useState } from 'react'
+
+import { cn } from '@/lib/utils'
+
+interface Sparkle {
+	id: string
+	x: string
+	y: string
+	color: string
+	delay: number
+	scale: number
+	lifespan: number
+}
+
+const Sparkle: React.FC<Sparkle> = ({ id, x, y, color, delay, scale }) => {
+	return (
+		<motion.svg
+			key={id}
+			className="pointer-events-none absolute z-20"
+			initial={{ opacity: 0, left: x, top: y }}
+			animate={{
+				opacity: [0, 1, 0],
+				scale: [0, scale, 0],
+				rotate: [75, 120, 150],
+			}}
+			transition={{ duration: 0.8, repeat: Infinity, delay }}
+			width="21"
+			height="21"
+			viewBox="0 0 21 21"
+		>
+			<path
+				d="M9.82531 0.843845C10.0553 0.215178 10.9446 0.215178 11.1746 0.843845L11.8618 2.72026C12.4006 4.19229 12.3916 6.39157 13.5 7.5C14.6084 8.60843 16.8077 8.59935 18.2797 9.13822L20.1561 9.82534C20.7858 10.0553 20.7858 10.9447 20.1561 11.1747L18.2797 11.8618C16.8077 12.4007 14.6084 12.3916 13.5 13.5C12.3916 14.6084 12.4006 16.8077 11.8618 18.2798L11.1746 20.1562C10.9446 20.7858 10.0553 20.7858 9.82531 20.1562L9.13819 18.2798C8.59932 16.8077 8.60843 14.6084 7.5 13.5C6.39157 12.3916 4.19225 12.4007 2.72023 11.8618L0.843814 11.1747C0.215148 10.9447 0.215148 10.0553 0.843814 9.82534L2.72023 9.13822C4.19225 8.59935 6.39157 8.60843 7.5 7.5C8.60843 6.39157 8.59932 4.19229 9.13819 2.72026L9.82531 0.843845Z"
+				fill={color}
+			/>
+		</motion.svg>
+	)
+}
+
+interface SparklesTextProps {
+	/**
+	 * @default <div />
+	 * @type ReactElement
+	 * @description
+	 * The component to be rendered as the text
+	 * */
+	as?: ReactElement
+
+	/**
+	 * @default ""
+	 * @type string
+	 * @description
+	 * The className of the text
+	 */
+	className?: string
+
+	/**
+	 * @required
+	 * @type ReactNode
+	 * @description
+	 * The content to be displayed
+	 * */
+	children: React.ReactNode
+
+	/**
+	 * @default 10
+	 * @type number
+	 * @description
+	 * The count of sparkles
+	 * */
+	sparklesCount?: number
+
+	/**
+	 * @default "{first: '#9E7AFF', second: '#FE8BBB'}"
+	 * @type string
+	 * @description
+	 * The colors of the sparkles
+	 * */
+	colors?: {
+		first: string
+		second: string
+	}
+}
+
+export const SparklesText: React.FC<SparklesTextProps> = ({
+	children,
+	colors = { first: '#9E7AFF', second: '#FE8BBB' },
+	className,
+	sparklesCount = 10,
+	...props
+}) => {
+	const [sparkles, setSparkles] = useState<Sparkle[]>([])
+
+	useEffect(() => {
+		const generateStar = (): Sparkle => {
+			const starX = `${Math.random() * 100}%`
+			const starY = `${Math.random() * 100}%`
+			const color = Math.random() > 0.5 ? colors.first : colors.second
+			const delay = Math.random() * 2
+			const scale = Math.random() * 1 + 0.3
+			const lifespan = Math.random() * 10 + 5
+			const id = `${starX}-${starY}-${Date.now()}`
+			return { id, x: starX, y: starY, color, delay, scale, lifespan }
+		}
+
+		const initializeStars = () => {
+			const newSparkles = Array.from({ length: sparklesCount }, generateStar)
+			setSparkles(newSparkles)
+		}
+
+		const updateStars = () => {
+			setSparkles((currentSparkles) =>
+				currentSparkles.map((star) => {
+					if (star.lifespan <= 0) {
+						return generateStar()
+					} else {
+						return { ...star, lifespan: star.lifespan - 0.1 }
+					}
+				})
+			)
+		}
+
+		initializeStars()
+		const interval = setInterval(updateStars, 100)
+
+		return () => clearInterval(interval)
+	}, [colors.first, colors.second, sparklesCount])
+
+	return (
+		<div
+			className={cn('text-6xl font-bold', className)}
+			{...props}
+			style={
+				{
+					'--sparkles-first-color': `${colors.first}`,
+					'--sparkles-second-color': `${colors.second}`,
+				} as CSSProperties
+			}
+		>
+			<span className="relative inline-block">
+				{sparkles.map((sparkle) => (
+					<Sparkle key={sparkle.id} {...sparkle} />
+				))}
+				<strong className="bg-linear-to-r from-[var(--sparkles-first-color)] to-[var(--sparkles-second-color)] bg-clip-text text-transparent">
+					{children}
+				</strong>
+			</span>
+		</div>
+	)
+}
diff --git a/packages/website/src/components/ui/spinner.tsx b/packages/website/src/components/ui/spinner.tsx
new file mode 100644
index 0000000..b45047c
--- /dev/null
+++ b/packages/website/src/components/ui/spinner.tsx
@@ -0,0 +1,16 @@
+import { Loader2Icon } from 'lucide-react'
+
+import { cn } from '@/lib/utils'
+
+function Spinner({ className, ...props }: React.ComponentProps<'svg'>) {
+	return (
+		<Loader2Icon
+			role="status"
+			aria-label="Loading"
+			className={cn('size-4 animate-spin', className)}
+			{...props}
+		/>
+	)
+}
+
+export { Spinner }
diff --git a/packages/website/src/components/ui/switch.tsx b/packages/website/src/components/ui/switch.tsx
new file mode 100644
index 0000000..8c29424
--- /dev/null
+++ b/packages/website/src/components/ui/switch.tsx
@@ -0,0 +1,26 @@
+import * as SwitchPrimitive from '@radix-ui/react-switch'
+import * as React from 'react'
+
+import { cn } from '@/lib/utils'
+
+function Switch({ className, ...props }: React.ComponentProps<typeof SwitchPrimitive.Root>) {
+	return (
+		<SwitchPrimitive.Root
+			data-slot="switch"
+			className={cn(
+				'peer data-[state=checked]:bg-primary data-[state=unchecked]:bg-input focus-visible:border-ring focus-visible:ring-ring/50 dark:data-[state=unchecked]:bg-input/80 inline-flex h-[1.15rem] w-8 shrink-0 items-center rounded-full border border-transparent shadow-xs transition-all outline-none focus-visible:ring-[3px] disabled:cursor-not-allowed disabled:opacity-50',
+				className
+			)}
+			{...props}
+		>
+			<SwitchPrimitive.Thumb
+				data-slot="switch-thumb"
+				className={cn(
+					'bg-background dark:data-[state=unchecked]:bg-foreground dark:data-[state=checked]:bg-primary-foreground pointer-events-none block size-4 rounded-full ring-0 transition-transform data-[state=checked]:translate-x-[calc(100%-2px)] data-[state=unchecked]:translate-x-0'
+				)}
+			/>
+		</SwitchPrimitive.Root>
+	)
+}
+
+export { Switch }
diff --git a/packages/website/src/components/ui/text-animate.tsx b/packages/website/src/components/ui/text-animate.tsx
new file mode 100644
index 0000000..ae7ef9b
--- /dev/null
+++ b/packages/website/src/components/ui/text-animate.tsx
@@ -0,0 +1,417 @@
+import { AnimatePresence, MotionProps, Variants, motion } from 'motion/react'
+import { ElementType, memo } from 'react'
+
+import { cn } from '@/lib/utils'
+
+type AnimationType = 'text' | 'word' | 'character' | 'line'
+type AnimationVariant =
+	| 'fadeIn'
+	| 'blurIn'
+	| 'blurInUp'
+	| 'blurInDown'
+	| 'slideUp'
+	| 'slideDown'
+	| 'slideLeft'
+	| 'slideRight'
+	| 'scaleUp'
+	| 'scaleDown'
+
+interface TextAnimateProps extends MotionProps {
+	/**
+	 * The text content to animate
+	 */
+	children: string
+	/**
+	 * The class name to be applied to the component
+	 */
+	className?: string
+	/**
+	 * The class name to be applied to each segment
+	 */
+	segmentClassName?: string
+	/**
+	 * The delay before the animation starts
+	 */
+	delay?: number
+	/**
+	 * The duration of the animation
+	 */
+	duration?: number
+	/**
+	 * Custom motion variants for the animation
+	 */
+	variants?: Variants
+	/**
+	 * The element type to render
+	 */
+	as?: ElementType
+	/**
+	 * How to split the text ("text", "word", "character")
+	 */
+	by?: AnimationType
+	/**
+	 * Whether to start animation when component enters viewport
+	 */
+	startOnView?: boolean
+	/**
+	 * Whether to animate only once
+	 */
+	once?: boolean
+	/**
+	 * The animation preset to use
+	 */
+	animation?: AnimationVariant
+	/**
+	 * Whether to enable accessibility features (default: true)
+	 */
+	accessible?: boolean
+}
+
+const staggerTimings: Record<AnimationType, number> = {
+	text: 0.06,
+	word: 0.05,
+	character: 0.03,
+	line: 0.06,
+}
+
+const defaultContainerVariants = {
+	hidden: { opacity: 1 },
+	show: {
+		opacity: 1,
+		transition: {
+			delayChildren: 0,
+			staggerChildren: 0.05,
+		},
+	},
+	exit: {
+		opacity: 0,
+		transition: {
+			staggerChildren: 0.05,
+			staggerDirection: -1,
+		},
+	},
+}
+
+const defaultItemVariants: Variants = {
+	hidden: { opacity: 0 },
+	show: {
+		opacity: 1,
+	},
+	exit: {
+		opacity: 0,
+	},
+}
+
+const defaultItemAnimationVariants: Record<
+	AnimationVariant,
+	{ container: Variants; item: Variants }
+> = {
+	fadeIn: {
+		container: defaultContainerVariants,
+		item: {
+			hidden: { opacity: 0, y: 20 },
+			show: {
+				opacity: 1,
+				y: 0,
+				transition: {
+					duration: 0.3,
+				},
+			},
+			exit: {
+				opacity: 0,
+				y: 20,
+				transition: { duration: 0.3 },
+			},
+		},
+	},
+	blurIn: {
+		container: defaultContainerVariants,
+		item: {
+			hidden: { opacity: 0, filter: 'blur(10px)' },
+			show: {
+				opacity: 1,
+				filter: 'blur(0px)',
+				transition: {
+					duration: 0.3,
+				},
+			},
+			exit: {
+				opacity: 0,
+				filter: 'blur(10px)',
+				transition: { duration: 0.3 },
+			},
+		},
+	},
+	blurInUp: {
+		container: defaultContainerVariants,
+		item: {
+			hidden: { opacity: 0, filter: 'blur(10px)', y: 20 },
+			show: {
+				opacity: 1,
+				filter: 'blur(0px)',
+				y: 0,
+				transition: {
+					y: { duration: 0.3 },
+					opacity: { duration: 0.4 },
+					filter: { duration: 0.3 },
+				},
+			},
+			exit: {
+				opacity: 0,
+				filter: 'blur(10px)',
+				y: 20,
+				transition: {
+					y: { duration: 0.3 },
+					opacity: { duration: 0.4 },
+					filter: { duration: 0.3 },
+				},
+			},
+		},
+	},
+	blurInDown: {
+		container: defaultContainerVariants,
+		item: {
+			hidden: { opacity: 0, filter: 'blur(10px)', y: -20 },
+			show: {
+				opacity: 1,
+				filter: 'blur(0px)',
+				y: 0,
+				transition: {
+					y: { duration: 0.3 },
+					opacity: { duration: 0.4 },
+					filter: { duration: 0.3 },
+				},
+			},
+		},
+	},
+	slideUp: {
+		container: defaultContainerVariants,
+		item: {
+			hidden: { y: 20, opacity: 0 },
+			show: {
+				y: 0,
+				opacity: 1,
+				transition: {
+					duration: 0.3,
+				},
+			},
+			exit: {
+				y: -20,
+				opacity: 0,
+				transition: {
+					duration: 0.3,
+				},
+			},
+		},
+	},
+	slideDown: {
+		container: defaultContainerVariants,
+		item: {
+			hidden: { y: -20, opacity: 0 },
+			show: {
+				y: 0,
+				opacity: 1,
+				transition: { duration: 0.3 },
+			},
+			exit: {
+				y: 20,
+				opacity: 0,
+				transition: { duration: 0.3 },
+			},
+		},
+	},
+	slideLeft: {
+		container: defaultContainerVariants,
+		item: {
+			hidden: { x: 20, opacity: 0 },
+			show: {
+				x: 0,
+				opacity: 1,
+				transition: { duration: 0.3 },
+			},
+			exit: {
+				x: -20,
+				opacity: 0,
+				transition: { duration: 0.3 },
+			},
+		},
+	},
+	slideRight: {
+		container: defaultContainerVariants,
+		item: {
+			hidden: { x: -20, opacity: 0 },
+			show: {
+				x: 0,
+				opacity: 1,
+				transition: { duration: 0.3 },
+			},
+			exit: {
+				x: 20,
+				opacity: 0,
+				transition: { duration: 0.3 },
+			},
+		},
+	},
+	scaleUp: {
+		container: defaultContainerVariants,
+		item: {
+			hidden: { scale: 0.5, opacity: 0 },
+			show: {
+				scale: 1,
+				opacity: 1,
+				transition: {
+					duration: 0.3,
+					scale: {
+						type: 'spring',
+						damping: 15,
+						stiffness: 300,
+					},
+				},
+			},
+			exit: {
+				scale: 0.5,
+				opacity: 0,
+				transition: { duration: 0.3 },
+			},
+		},
+	},
+	scaleDown: {
+		container: defaultContainerVariants,
+		item: {
+			hidden: { scale: 1.5, opacity: 0 },
+			show: {
+				scale: 1,
+				opacity: 1,
+				transition: {
+					duration: 0.3,
+					scale: {
+						type: 'spring',
+						damping: 15,
+						stiffness: 300,
+					},
+				},
+			},
+			exit: {
+				scale: 1.5,
+				opacity: 0,
+				transition: { duration: 0.3 },
+			},
+		},
+	},
+}
+
+const TextAnimateBase = ({
+	children,
+	delay = 0,
+	duration = 0.3,
+	variants,
+	className,
+	segmentClassName,
+	as: Component = 'p',
+	startOnView = true,
+	once = false,
+	by = 'word',
+	animation = 'fadeIn',
+	accessible = true,
+	...props
+}: TextAnimateProps) => {
+	const MotionComponent = motion.create(Component)
+
+	let segments: string[] = []
+	switch (by) {
+		case 'word':
+			segments = children.split(/(\s+)/)
+			break
+		case 'character':
+			segments = children.split('')
+			break
+		case 'line':
+			segments = children.split('\n')
+			break
+		case 'text':
+		default:
+			segments = [children]
+			break
+	}
+
+	const finalVariants = variants
+		? {
+				container: {
+					hidden: { opacity: 0 },
+					show: {
+						opacity: 1,
+						transition: {
+							opacity: { duration: 0.01, delay },
+							delayChildren: delay,
+							staggerChildren: duration / segments.length,
+						},
+					},
+					exit: {
+						opacity: 0,
+						transition: {
+							staggerChildren: duration / segments.length,
+							staggerDirection: -1,
+						},
+					},
+				},
+				item: variants,
+			}
+		: animation
+			? {
+					container: {
+						...defaultItemAnimationVariants[animation].container,
+						show: {
+							...defaultItemAnimationVariants[animation].container.show,
+							transition: {
+								delayChildren: delay,
+								staggerChildren: duration / segments.length,
+							},
+						},
+						exit: {
+							...defaultItemAnimationVariants[animation].container.exit,
+							transition: {
+								staggerChildren: duration / segments.length,
+								staggerDirection: -1,
+							},
+						},
+					},
+					item: defaultItemAnimationVariants[animation].item,
+				}
+			: { container: defaultContainerVariants, item: defaultItemVariants }
+
+	return (
+		<AnimatePresence mode="popLayout">
+			<MotionComponent
+				variants={finalVariants.container as Variants}
+				initial="hidden"
+				whileInView={startOnView ? 'show' : undefined}
+				animate={startOnView ? undefined : 'show'}
+				exit="exit"
+				className={cn('whitespace-pre-wrap', className)}
+				viewport={{ once }}
+				aria-label={accessible ? children : undefined}
+				{...props}
+			>
+				{accessible && <span className="sr-only">{children}</span>}
+				{segments.map((segment, i) => (
+					<motion.span
+						key={`${by}-${segment}-${i}`}
+						variants={finalVariants.item}
+						custom={i * staggerTimings[by]}
+						className={cn(
+							by === 'line' ? 'block' : 'inline-block whitespace-pre',
+							by === 'character' && '',
+							segmentClassName
+						)}
+						aria-hidden={accessible ? true : undefined}
+					>
+						{segment}
+					</motion.span>
+				))}
+			</MotionComponent>
+		</AnimatePresence>
+	)
+}
+
+// Export the memoized version
+export const TextAnimate = memo(TextAnimateBase)
diff --git a/packages/website/src/components/ui/tooltip.tsx b/packages/website/src/components/ui/tooltip.tsx
new file mode 100644
index 0000000..7781c0e
--- /dev/null
+++ b/packages/website/src/components/ui/tooltip.tsx
@@ -0,0 +1,55 @@
+import * as TooltipPrimitive from '@radix-ui/react-tooltip'
+import * as React from 'react'
+
+import { cn } from '@/lib/utils'
+
+function TooltipProvider({
+	delayDuration = 0,
+	...props
+}: React.ComponentProps<typeof TooltipPrimitive.Provider>) {
+	return (
+		<TooltipPrimitive.Provider
+			data-slot="tooltip-provider"
+			delayDuration={delayDuration}
+			{...props}
+		/>
+	)
+}
+
+function Tooltip({ ...props }: React.ComponentProps<typeof TooltipPrimitive.Root>) {
+	return (
+		<TooltipProvider>
+			<TooltipPrimitive.Root data-slot="tooltip" {...props} />
+		</TooltipProvider>
+	)
+}
+
+function TooltipTrigger({ ...props }: React.ComponentProps<typeof TooltipPrimitive.Trigger>) {
+	return <TooltipPrimitive.Trigger data-slot="tooltip-trigger" {...props} />
+}
+
+function TooltipContent({
+	className,
+	sideOffset = 0,
+	children,
+	...props
+}: React.ComponentProps<typeof TooltipPrimitive.Content>) {
+	return (
+		<TooltipPrimitive.Portal>
+			<TooltipPrimitive.Content
+				data-slot="tooltip-content"
+				sideOffset={sideOffset}
+				className={cn(
+					'bg-foreground text-background animate-in fade-in-0 zoom-in-95 data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=closed]:zoom-out-95 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 z-50 w-fit origin-(--radix-tooltip-content-transform-origin) rounded-md px-3 py-1.5 text-xs text-balance',
+					className
+				)}
+				{...props}
+			>
+				{children}
+				<TooltipPrimitive.Arrow className="bg-foreground fill-foreground z-50 size-2.5 translate-y-[calc(-50%_-_2px)] rotate-45 rounded-[2px]" />
+			</TooltipPrimitive.Content>
+		</TooltipPrimitive.Portal>
+	)
+}
+
+export { Tooltip, TooltipTrigger, TooltipContent, TooltipProvider }
diff --git a/packages/website/src/components/ui/typing-animation.tsx b/packages/website/src/components/ui/typing-animation.tsx
new file mode 100644
index 0000000..f9898df
--- /dev/null
+++ b/packages/website/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>
+	)
+}
diff --git a/packages/website/src/constants.ts b/packages/website/src/constants.ts
new file mode 100644
index 0000000..218d8aa
--- /dev/null
+++ b/packages/website/src/constants.ts
@@ -0,0 +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.12.1/dist/iife/page-agent.demo.js'
+export const CDN_DEMO_CN_URL =
+	'https://registry.npmmirror.com/page-agent/1.12.1/files/dist/iife/page-agent.demo.js'
+
+// 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 = ''
diff --git a/packages/website/src/env.d.ts b/packages/website/src/env.d.ts
new file mode 100644
index 0000000..e867e23
--- /dev/null
+++ b/packages/website/src/env.d.ts
@@ -0,0 +1,10 @@
+/// <reference types="vite/client" />
+
+interface ImportMetaEnv {
+	readonly VERSION: string
+}
+
+declare module '*.module.css' {
+	const classes: Record<string, string>
+	export default classes
+}
diff --git a/packages/website/src/hooks/useGitHubStars.ts b/packages/website/src/hooks/useGitHubStars.ts
new file mode 100644
index 0000000..d5bd6e6
--- /dev/null
+++ b/packages/website/src/hooks/useGitHubStars.ts
@@ -0,0 +1,29 @@
+import { useEffect, useState } from 'react'
+
+const STATS_URL = 'https://page-agent.github.io/gh-stats/stats.json'
+
+let cached: number | null = null
+
+export function useGitHubStars() {
+	const [stars, setStars] = useState(cached)
+
+	useEffect(() => {
+		if (cached !== null) return
+		const controller = new AbortController()
+		fetch(STATS_URL, { signal: controller.signal })
+			.then((r) => r.json())
+			.then((data) => {
+				cached = data.stargazers_count ?? null
+				setStars(cached)
+			})
+			.catch(() => {})
+		return () => controller.abort()
+	}, [])
+
+	return stars
+}
+
+export function formatStars(n: number): string {
+	if (n >= 1000) return `${(n / 1000).toFixed(1).replace(/\.0$/, '')}k`
+	return String(n)
+}
diff --git a/packages/website/src/i18n/context.tsx b/packages/website/src/i18n/context.tsx
new file mode 100644
index 0000000..499950b
--- /dev/null
+++ b/packages/website/src/i18n/context.tsx
@@ -0,0 +1,34 @@
+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, setLanguage] = 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 switchLanguage = (lang: Lang) => {
+		setLanguage(lang)
+		localStorage.setItem('language', lang)
+	}
+
+	return (
+		<LanguageContext value={{ language, isZh: language === 'zh-CN', setLanguage: switchLanguage }}>
+			{children}
+		</LanguageContext>
+	)
+}
+
+export function useLanguage() {
+	const ctx = use(LanguageContext)
+	if (!ctx) throw new Error('useLanguage must be used within LanguageProvider')
+	return ctx
+}
diff --git a/packages/website/src/index.css b/packages/website/src/index.css
new file mode 100644
index 0000000..32503da
--- /dev/null
+++ b/packages/website/src/index.css
@@ -0,0 +1,471 @@
+@config '../tailwind.config.js';
+@import 'tailwindcss';
+@import 'tw-animate-css';
+
+@custom-variant dark (&:is(.dark *));
+
+/* 启用 class-based dark mode for Tailwind v4 */
+@variant dark (.dark &);
+
+:root {
+	--background: oklch(1 0 0);
+	--foreground: oklch(0.145 0 0);
+	/* 主题色渐变 */
+	--theme-color-1: rgb(88, 192, 252);
+	--theme-color-2: rgb(189, 69, 251);
+
+	/* shadcn */
+	--radius: 0.625rem;
+	--card: oklch(1 0 0);
+	--card-foreground: oklch(0.145 0 0);
+	--popover: oklch(1 0 0);
+	--popover-foreground: oklch(0.145 0 0);
+	--primary: oklch(0.205 0 0);
+	--primary-foreground: oklch(0.985 0 0);
+	--secondary: oklch(0.97 0 0);
+	--secondary-foreground: oklch(0.205 0 0);
+	--muted: oklch(0.97 0 0);
+	--muted-foreground: oklch(0.556 0 0);
+	--accent: oklch(0.97 0 0);
+	--accent-foreground: oklch(0.205 0 0);
+	--destructive: oklch(0.577 0.245 27.325);
+	--border: oklch(0.922 0 0);
+	--input: oklch(0.922 0 0);
+	--ring: oklch(0.708 0 0);
+	--chart-1: oklch(0.646 0.222 41.116);
+	--chart-2: oklch(0.6 0.118 184.704);
+	--chart-3: oklch(0.398 0.07 227.392);
+	--chart-4: oklch(0.828 0.189 84.429);
+	--chart-5: oklch(0.769 0.188 70.08);
+	--sidebar: oklch(0.985 0 0);
+	--sidebar-foreground: oklch(0.145 0 0);
+	--sidebar-primary: oklch(0.205 0 0);
+	--sidebar-primary-foreground: oklch(0.985 0 0);
+	--sidebar-accent: oklch(0.97 0 0);
+	--sidebar-accent-foreground: oklch(0.205 0 0);
+	--sidebar-border: oklch(0.922 0 0);
+	--sidebar-ring: oklch(0.708 0 0);
+}
+
+/* class-based dark mode - 应用到 html.dark */
+html.dark,
+:root.dark {
+	--background: #0a0a0a;
+	--foreground: #ededed;
+}
+
+/* 同时支持系统偏好 */
+/* @media (prefers-color-scheme: dark) {
+	html:not(.light),
+	:root:not(.light) {
+		--background: #0a0a0a;
+		--foreground: #ededed;
+	}
+} */
+
+/* 添加 Tailwind 自定义颜色 */
+@theme {
+	--color-background: var(--background);
+	--color-foreground: var(--foreground);
+}
+
+body {
+	background: var(--background);
+	color: var(--foreground);
+	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;
+}
+
+/* 文档标题层级需要比正文标题更清晰，避免 h2/h3/h4 视觉差异过小。 */
+.prose h1,
+.prose h2,
+.prose h3,
+.prose h4,
+.prose h5,
+.prose h6 {
+	font-weight: 480;
+	line-height: 1.25;
+	letter-spacing: -0.015em;
+}
+
+.prose h2[id] {
+	margin-bottom: 1rem;
+	padding-bottom: 0.45rem;
+	border-bottom: 1px solid rgba(23, 23, 23, 0.12);
+	font-size: 1.875rem;
+	font-weight: 650;
+}
+
+.prose h3[id] {
+	margin-bottom: 0.75rem;
+	font-size: 1.375rem;
+	font-weight: 600;
+}
+
+.prose h4[id] {
+	margin-bottom: 0.5rem;
+	font-size: 1.0625rem;
+	font-weight: 560;
+	letter-spacing: -0.005em;
+}
+
+.dark .prose h2[id] {
+	border-bottom-color: rgba(255, 255, 255, 0.14);
+}
+
+/* strong/b 也用中等字重 */
+.prose strong,
+.prose b {
+	font-weight: 480;
+}
+
+/* 确保文档页面标题在暗色模式下可见 - 只针对 prose 内的标题 */
+.prose h1,
+.prose h2,
+.prose h3,
+.prose h4,
+.prose h5,
+.prose h6 {
+	color: rgba(23, 23, 23, 0.85);
+}
+
+.dark .prose h1,
+.dark .prose h2,
+.dark .prose h3,
+.dark .prose h4,
+.dark .prose h5,
+.dark .prose h6 {
+	color: rgba(255, 255, 255, 0.9);
+}
+
+table,
+th,
+td {
+	color: #171717;
+}
+
+.dark table,
+.dark th,
+.dark td {
+	color: #ededed;
+}
+
+/* 文档页深色模式优化 */
+.dark .prose {
+	color: rgba(255, 255, 255, 0.7);
+}
+
+/* @media (prefers-color-scheme: dark) {
+	:root:not(.light) .prose {
+		color: rgba(255, 255, 255, 0.7);
+	}
+} */
+
+.dark .dark\:prose-invert {
+	--tw-prose-body: rgba(255, 255, 255, 0.7);
+	--tw-prose-headings: rgba(255, 255, 255, 0.95);
+	--tw-prose-lead: rgba(255, 255, 255, 0.7);
+	--tw-prose-links: rgba(147, 197, 253, 0.9);
+	--tw-prose-bold: rgba(255, 255, 255, 0.9);
+	--tw-prose-counters: rgba(255, 255, 255, 0.6);
+	--tw-prose-bullets: rgba(255, 255, 255, 0.5);
+	--tw-prose-hr: rgba(255, 255, 255, 0.2);
+	--tw-prose-quotes: rgba(255, 255, 255, 0.8);
+	--tw-prose-quote-borders: rgba(255, 255, 255, 0.3);
+	--tw-prose-captions: rgba(255, 255, 255, 0.6);
+	--tw-prose-code: rgba(255, 255, 255, 0.9);
+	--tw-prose-pre-code: rgba(255, 255, 255, 0.95);
+	--tw-prose-pre-bg: rgba(0, 0, 0, 0.5);
+	--tw-prose-th-borders: rgba(255, 255, 255, 0.3);
+	--tw-prose-td-borders: rgba(255, 255, 255, 0.2);
+}
+
+/* @media (prefers-color-scheme: dark) {
+	:root:not(.light) .dark\:prose-invert {
+		--tw-prose-body: rgba(255, 255, 255, 0.7);
+		--tw-prose-headings: rgba(255, 255, 255, 0.95);
+		--tw-prose-lead: rgba(255, 255, 255, 0.7);
+		--tw-prose-links: rgba(147, 197, 253, 0.9);
+		--tw-prose-bold: rgba(255, 255, 255, 0.9);
+		--tw-prose-counters: rgba(255, 255, 255, 0.6);
+		--tw-prose-bullets: rgba(255, 255, 255, 0.5);
+		--tw-prose-hr: rgba(255, 255, 255, 0.2);
+		--tw-prose-quotes: rgba(255, 255, 255, 0.8);
+		--tw-prose-quote-borders: rgba(255, 255, 255, 0.3);
+		--tw-prose-captions: rgba(255, 255, 255, 0.6);
+		--tw-prose-code: rgba(255, 255, 255, 0.9);
+		--tw-prose-pre-code: rgba(255, 255, 255, 0.95);
+		--tw-prose-pre-bg: rgba(0, 0, 0, 0.5);
+		--tw-prose-th-borders: rgba(255, 255, 255, 0.3);
+		--tw-prose-td-borders: rgba(255, 255, 255, 0.2);
+	}
+} */
+
+/* 标题更清晰 */
+.dark .prose h1,
+.dark .prose h2,
+.dark .prose h3,
+.dark .prose h4 {
+	color: rgba(255, 255, 255, 0.95);
+}
+
+/* @media (prefers-color-scheme: dark) {
+	:root:not(.light) .prose h1,
+	:root:not(.light) .prose h2,
+	:root:not(.light) .prose h3,
+	:root:not(.light) .prose h4 {
+		color: rgba(255, 255, 255, 0.95);
+	}
+} */
+
+/* 链接更清晰 */
+.dark .prose a {
+	color: rgba(147, 197, 253, 0.9);
+}
+
+/* @media (prefers-color-scheme: dark) {
+	:root:not(.light) .prose a {
+		color: rgba(147, 197, 253, 0.9);
+	}
+} */
+
+/* 代码块背景更黑 */
+.dark .prose pre {
+	background-color: rgba(0, 0, 0, 0.6);
+}
+
+/* @media (prefers-color-scheme: dark) {
+	:root:not(.light) .prose pre {
+		background-color: rgba(0, 0, 0, 0.6);
+	}
+} */
+
+/* 表格样式 */
+.dark .prose table {
+	color: rgba(255, 255, 255, 0.7);
+}
+
+/* @media (prefers-color-scheme: dark) {
+	:root:not(.light) .prose table {
+		color: rgba(255, 255, 255, 0.7);
+	}
+} */
+
+.dark .prose thead {
+	color: rgba(255, 255, 255, 0.9);
+	border-bottom-color: rgba(255, 255, 255, 0.3);
+}
+
+/* @media (prefers-color-scheme: dark) {
+	:root:not(.light) .prose thead {
+		color: rgba(255, 255, 255, 0.9);
+		border-bottom-color: rgba(255, 255, 255, 0.3);
+	}
+} */
+
+.dark .prose tbody tr {
+	border-bottom-color: rgba(255, 255, 255, 0.2);
+}
+
+/* @media (prefers-color-scheme: dark) {
+	:root:not(.light) .prose tbody tr {
+		border-bottom-color: rgba(255, 255, 255, 0.2);
+	}
+} */
+
+/* 隐藏滚动条，但保持滚动功能 */
+.scrollbar-hide {
+	-ms-overflow-style: none; /* IE and Edge */
+	scrollbar-width: none; /* Firefox */
+}
+
+.scrollbar-hide::-webkit-scrollbar {
+	display: none; /* Chrome, Safari and Opera */
+}
+
+/* shadcn */
+@theme inline {
+	--radius-sm: calc(var(--radius) - 4px);
+	--radius-md: calc(var(--radius) - 2px);
+	--radius-lg: var(--radius);
+	--radius-xl: calc(var(--radius) + 4px);
+	--radius-2xl: calc(var(--radius) + 8px);
+	--radius-3xl: calc(var(--radius) + 12px);
+	--radius-4xl: calc(var(--radius) + 16px);
+	--color-background: var(--background);
+	--color-foreground: var(--foreground);
+	--color-card: var(--card);
+	--color-card-foreground: var(--card-foreground);
+	--color-popover: var(--popover);
+	--color-popover-foreground: var(--popover-foreground);
+	--color-primary: var(--primary);
+	--color-primary-foreground: var(--primary-foreground);
+	--color-secondary: var(--secondary);
+	--color-secondary-foreground: var(--secondary-foreground);
+	--color-muted: var(--muted);
+	--color-muted-foreground: var(--muted-foreground);
+	--color-accent: var(--accent);
+	--color-accent-foreground: var(--accent-foreground);
+	--color-destructive: var(--destructive);
+	--color-border: var(--border);
+	--color-input: var(--input);
+	--color-ring: var(--ring);
+	--color-chart-1: var(--chart-1);
+	--color-chart-2: var(--chart-2);
+	--color-chart-3: var(--chart-3);
+	--color-chart-4: var(--chart-4);
+	--color-chart-5: var(--chart-5);
+	--color-sidebar: var(--sidebar);
+	--color-sidebar-foreground: var(--sidebar-foreground);
+	--color-sidebar-primary: var(--sidebar-primary);
+	--color-sidebar-primary-foreground: var(--sidebar-primary-foreground);
+	--color-sidebar-accent: var(--sidebar-accent);
+	--color-sidebar-accent-foreground: var(--sidebar-accent-foreground);
+	--color-sidebar-border: var(--sidebar-border);
+	--color-sidebar-ring: var(--sidebar-ring);
+
+	/* magic ui */
+	--animate-blink-cursor: blink-cursor 1.2s step-end infinite;
+	@keyframes blink-cursor {
+		0%,
+		49% {
+			opacity: 1;
+		}
+		50%,
+		100% {
+			opacity: 0;
+		}
+	}
+	--animate-aurora: aurora 8s ease-in-out infinite alternate;
+	@keyframes aurora {
+		0% {
+			background-position: 0% 50%;
+			transform: rotate(-5deg) scale(0.9);
+		}
+		25% {
+			background-position: 50% 100%;
+			transform: rotate(5deg) scale(1.1);
+		}
+		50% {
+			background-position: 100% 50%;
+			transform: rotate(-3deg) scale(0.95);
+		}
+		75% {
+			background-position: 50% 0%;
+			transform: rotate(3deg) scale(1.05);
+		}
+		100% {
+			background-position: 0% 50%;
+			transform: rotate(-5deg) scale(0.9);
+		}
+	}
+	--animate-shiny-text: shiny-text 8s infinite;
+	@keyframes shiny-text {
+		0%,
+		90%,
+		100% {
+			background-position: calc(-100% - var(--shiny-width)) 0;
+		}
+		30%,
+		60% {
+			background-position: calc(100% + var(--shiny-width)) 0;
+		}
+	}
+	--animate-gradient: gradient 8s linear infinite;
+	@keyframes gradient {
+		to {
+			background-position: var(--bg-size, 300%) 0;
+		}
+	}
+	--animate-background-position-spin: background-position-spin 3000ms infinite alternate;
+	@keyframes background-position-spin {
+		0% {
+			background-position: top center;
+		}
+		100% {
+			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 */
+.dark {
+	--background: oklch(0.145 0 0);
+	--foreground: oklch(0.985 0 0);
+	--card: oklch(0.205 0 0);
+	--card-foreground: oklch(0.985 0 0);
+	--popover: oklch(0.205 0 0);
+	--popover-foreground: oklch(0.985 0 0);
+	--primary: oklch(0.922 0 0);
+	--primary-foreground: oklch(0.205 0 0);
+	--secondary: oklch(0.269 0 0);
+	--secondary-foreground: oklch(0.985 0 0);
+	--muted: oklch(0.269 0 0);
+	--muted-foreground: oklch(0.708 0 0);
+	--accent: oklch(0.269 0 0);
+	--accent-foreground: oklch(0.985 0 0);
+	--destructive: oklch(0.704 0.191 22.216);
+	--border: oklch(1 0 0 / 10%);
+	--input: oklch(1 0 0 / 15%);
+	--ring: oklch(0.556 0 0);
+	--chart-1: oklch(0.488 0.243 264.376);
+	--chart-2: oklch(0.696 0.17 162.48);
+	--chart-3: oklch(0.769 0.188 70.08);
+	--chart-4: oklch(0.627 0.265 303.9);
+	--chart-5: oklch(0.645 0.246 16.439);
+	--sidebar: oklch(0.205 0 0);
+	--sidebar-foreground: oklch(0.985 0 0);
+	--sidebar-primary: oklch(0.488 0.243 264.376);
+	--sidebar-primary-foreground: oklch(0.985 0 0);
+	--sidebar-accent: oklch(0.269 0 0);
+	--sidebar-accent-foreground: oklch(0.985 0 0);
+	--sidebar-border: oklch(1 0 0 / 10%);
+	--sidebar-ring: oklch(0.556 0 0);
+}
+
+/* shadcn base */
+@layer base {
+	* {
+		@apply border-border outline-ring/50;
+	}
+	body {
+		@apply bg-background text-foreground;
+	}
+}
diff --git a/packages/website/src/lib/useDocumentTitle.ts b/packages/website/src/lib/useDocumentTitle.ts
new file mode 100644
index 0000000..1e18324
--- /dev/null
+++ b/packages/website/src/lib/useDocumentTitle.ts
@@ -0,0 +1,9 @@
+import { useEffect } from 'react'
+
+const DEFAULT_TITLE = 'PageAgent - The GUI Agent Living in Your Webpage'
+
+export function useDocumentTitle(title?: string) {
+	useEffect(() => {
+		document.title = title ? `${title} - PageAgent` : DEFAULT_TITLE
+	}, [title])
+}
diff --git a/packages/website/src/lib/utils.ts b/packages/website/src/lib/utils.ts
new file mode 100644
index 0000000..c15e7f7
--- /dev/null
+++ b/packages/website/src/lib/utils.ts
@@ -0,0 +1,6 @@
+import { type ClassValue, clsx } from 'clsx'
+import { twMerge } from 'tailwind-merge'
+
+export function cn(...inputs: ClassValue[]) {
+	return twMerge(clsx(inputs))
+}
diff --git a/packages/website/src/main.tsx b/packages/website/src/main.tsx
new file mode 100644
index 0000000..70b661f
--- /dev/null
+++ b/packages/website/src/main.tsx
@@ -0,0 +1,22 @@
+import { createRoot } from 'react-dom/client'
+import { Router } from 'wouter'
+
+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(
+	<LanguageProvider>
+		<Router base="/page-agent">
+			<PagesRouter />
+		</Router>
+	</LanguageProvider>
+)
diff --git a/packages/website/src/pages/docs/Layout.tsx b/packages/website/src/pages/docs/Layout.tsx
new file mode 100644
index 0000000..7ee0f33
--- /dev/null
+++ b/packages/website/src/pages/docs/Layout.tsx
@@ -0,0 +1,141 @@
+import { ReactNode } from 'react'
+import { siGooglechrome } from 'simple-icons'
+import { Link, useLocation } from 'wouter'
+
+import { SparklesText } from '@/components/ui/sparkles-text'
+import { useLanguage } from '@/i18n/context'
+import { useDocumentTitle } from '@/lib/useDocumentTitle'
+
+interface DocsLayoutProps {
+	children: ReactNode
+}
+
+interface NavItem {
+	title: string
+	path: string
+}
+
+interface NavSection {
+	title: string
+	items: NavItem[]
+}
+
+export default function DocsLayout({ children }: DocsLayoutProps) {
+	const { isZh } = useLanguage()
+	const [rawLocation] = useLocation()
+	const location = rawLocation.replace(/\/+$/, '')
+
+	const navigationSections: NavSection[] = [
+		{
+			title: isZh ? '介绍' : 'Introduction',
+			items: [
+				{ title: isZh ? '概览' : 'Overview', path: '/introduction/overview' },
+				{ title: isZh ? '快速开始' : 'Quick Start', path: '/introduction/quick-start' },
+				{ title: isZh ? '使用限制' : 'Limitations', path: '/introduction/limitations' },
+				{
+					title: isZh ? '故障排查' : 'Troubleshooting',
+					path: '/introduction/troubleshooting',
+				},
+			],
+		},
+		{
+			title: isZh ? '功能特性' : 'Features',
+			items: [
+				{ title: isZh ? '模型' : 'Models', path: '/features/models' },
+				{ title: isZh ? '自定义工具' : 'Custom Tools', path: '/features/custom-tools' },
+				{ title: isZh ? '知识注入' : 'Instructions', path: '/features/custom-instructions' },
+				{ title: isZh ? '数据脱敏' : 'Data Masking', path: '/features/data-masking' },
+				{ title: isZh ? 'Chrome 扩展' : 'Chrome Extension', path: '/features/chrome-extension' },
+				{ title: 'MCP Server (Beta)', path: '/features/mcp-server' },
+				{
+					title: isZh ? '接入第三方 Agent' : 'Third-party Agent',
+					path: '/features/third-party-agent',
+				},
+			],
+		},
+		{
+			title: isZh ? '高级' : 'Advanced',
+			items: [
+				{ title: 'PageAgent', path: '/advanced/page-agent' },
+				{ title: 'PageAgentCore', path: '/advanced/page-agent-core' },
+				{ title: 'PageController', path: '/advanced/page-controller' },
+				{ title: isZh ? '自定义 UI' : 'Custom UI', path: '/advanced/custom-ui' },
+				{
+					title: '🚧 ' + (isZh ? '安全与权限' : 'Security & Permissions'),
+					path: '/advanced/security-permissions',
+				},
+			],
+		},
+	]
+
+	const activeTitle = navigationSections
+		.flatMap((s) => s.items)
+		.find((item) => item.path === location)?.title
+
+	useDocumentTitle(activeTitle)
+
+	return (
+		<div className="max-w-7xl mx-auto px-6 py-8 overflow-x-auto">
+			<div className="flex gap-8 min-w-225">
+				{/* Sidebar */}
+				<aside className="w-64 shrink-0" role="complementary" aria-label="文档导航">
+					<div className="sticky">
+						<nav className="space-y-8" role="navigation" aria-label="文档章节">
+							{navigationSections.map((section) => (
+								<section key={section.title}>
+									<h3 className="font-semibold text-gray-600 dark:text-gray-400 uppercase tracking-wider mb-3">
+										{section.title}
+									</h3>
+									<ul className="space-y-2" role="list">
+										{section.items.map((item) => {
+											const isActive = location === item.path
+											const isChromeExtension = item.path === '/features/chrome-extension'
+											return (
+												<li key={item.path}>
+													<Link
+														href={item.path}
+														className={`block px-3 py-2 rounded-lg transition-colors duration-200 ${
+															isActive
+																? 'bg-blue-100 dark:bg-blue-900/30 text-blue-700 dark:text-blue-300 font-medium'
+																: 'text-gray-600 dark:text-gray-300 hover:text-gray-900 dark:hover:text-white hover:bg-gray-100 dark:hover:bg-gray-800'
+														}`}
+														aria-current={isActive ? 'page' : undefined}
+													>
+														{isChromeExtension ? (
+															<span className="flex items-center gap-1.5">
+																<svg
+																	className="w-3.5 h-3.5 shrink-0"
+																	viewBox="0 0 24 24"
+																	aria-hidden="true"
+																>
+																	<path d={siGooglechrome.path} fill="currentColor" />
+																</svg>
+																<SparklesText
+																	className="text-[length:inherit] font-[inherit] font-medium"
+																	sparklesCount={3}
+																>
+																	{item.title}
+																</SparklesText>
+															</span>
+														) : (
+															item.title
+														)}
+													</Link>
+												</li>
+											)
+										})}
+									</ul>
+								</section>
+							))}
+						</nav>
+					</div>
+				</aside>
+
+				{/* Main Content */}
+				<main className="flex-1 min-w-0" id="main-content" role="main">
+					<div className="prose dark:prose-invert max-w-none">{children}</div>
+				</main>
+			</div>
+		</div>
+	)
+}
diff --git a/packages/website/src/pages/docs/advanced/custom-ui/page.tsx b/packages/website/src/pages/docs/advanced/custom-ui/page.tsx
new file mode 100644
index 0000000..788a32d
--- /dev/null
+++ b/packages/website/src/pages/docs/advanced/custom-ui/page.tsx
@@ -0,0 +1,272 @@
+import { APIDivider, APIReference } from '@/components/APIReference'
+import CodeEditor from '@/components/CodeEditor'
+import { Heading } from '@/components/Heading'
+import { useLanguage } from '@/i18n/context'
+
+export default function CustomUIDocs() {
+	const { isZh } = useLanguage()
+
+	return (
+		<div>
+			<h1 className="text-4xl font-bold mb-6">{isZh ? '自定义 UI' : 'Custom UI'}</h1>
+
+			<p className="text-xl text-gray-600 dark:text-gray-300 mb-8 leading-relaxed">
+				{isZh
+					? 'PageAgent 的核心逻辑（PageAgentCore）和 UI 完全解耦，通过事件通讯。你可以用自己的 UI 替换内置 Panel。'
+					: 'PageAgent core logic (PageAgentCore) is fully decoupled from UI through events. You can replace the built-in Panel with your own UI.'}
+			</p>
+
+			{/* Architecture */}
+			<section className="mb-10">
+				<Heading id="architecture">{isZh ? '架构' : 'Architecture'}</Heading>
+				<p className="text-gray-600 dark:text-gray-400 mb-4">
+					{isZh
+						? 'PageAgent 由三个独立模块组成，可自由组合：'
+						: 'PageAgent consists of three independent modules that can be freely combined:'}
+				</p>
+				<ul className="list-disc list-inside text-gray-600 dark:text-gray-400 space-y-2 mb-4">
+					<li>
+						<strong>PageAgentCore</strong> -{' '}
+						{isZh ? '核心 Agent 逻辑，不包含 UI' : 'Core agent logic, no UI'}
+					</li>
+					<li>
+						<strong>PageController</strong> -{' '}
+						{isZh ? 'DOM 操作和视觉反馈' : 'DOM operations and visual feedback'}
+					</li>
+					<li>
+						<strong>UI (Panel)</strong> -{' '}
+						{isZh
+							? '用户界面，可替换为自定义实现'
+							: 'User interface, replaceable with custom implementation'}
+					</li>
+				</ul>
+			</section>
+
+			<APIDivider title={isZh ? '事件系统' : 'Event System'} />
+
+			{/* Two Event Streams */}
+			<section className="mb-10">
+				<Heading id="two-event-streams">{isZh ? '两个事件流' : 'Two Event Streams'}</Heading>
+				<p className="text-gray-600 dark:text-gray-400 mb-4">
+					{isZh
+						? 'PageAgentCore 提供两种不同性质的事件流，方便 UI 渲染：'
+						: 'PageAgentCore provides two distinct event streams for UI rendering:'}
+				</p>
+
+				{/* Comparison Table */}
+				<div className="overflow-x-auto mb-6">
+					<table className="w-full border-collapse border border-gray-300 dark:border-gray-600">
+						<thead>
+							<tr className="bg-gray-100 dark:bg-gray-800">
+								<th className="border border-gray-300 dark:border-gray-600 px-4 py-2 text-left"></th>
+								<th className="border border-gray-300 dark:border-gray-600 px-4 py-2 text-left">
+									Historical Events
+								</th>
+								<th className="border border-gray-300 dark:border-gray-600 px-4 py-2 text-left">
+									Activity Events
+								</th>
+							</tr>
+						</thead>
+						<tbody>
+							<tr>
+								<td className="border border-gray-300 dark:border-gray-600 px-4 py-2">
+									{isZh ? '事件名' : 'Event Name'}
+								</td>
+								<td className="border border-gray-300 dark:border-gray-600 px-4 py-2">
+									<code>historychange</code>
+								</td>
+								<td className="border border-gray-300 dark:border-gray-600 px-4 py-2">
+									<code>activity</code>
+								</td>
+							</tr>
+							<tr>
+								<td className="border border-gray-300 dark:border-gray-600 px-4 py-2">
+									{isZh ? '持久性' : 'Persistence'}
+								</td>
+								<td className="border border-gray-300 dark:border-gray-600 px-4 py-2">
+									{isZh ? '持久化到 agent.history' : 'Persisted in agent.history'}
+								</td>
+								<td className="border border-gray-300 dark:border-gray-600 px-4 py-2">
+									{isZh ? '瞬态' : 'Transient'}
+								</td>
+							</tr>
+							<tr>
+								<td className="border border-gray-300 dark:border-gray-600 px-4 py-2">
+									{isZh ? '传给 LLM' : 'Sent to LLM'}
+								</td>
+								<td className="border border-gray-300 dark:border-gray-600 px-4 py-2">
+									{isZh ? '是' : 'Yes'}
+								</td>
+								<td className="border border-gray-300 dark:border-gray-600 px-4 py-2">
+									{isZh ? '否' : 'No'}
+								</td>
+							</tr>
+							<tr>
+								<td className="border border-gray-300 dark:border-gray-600 px-4 py-2">
+									{isZh ? '用途' : 'Purpose'}
+								</td>
+								<td className="border border-gray-300 dark:border-gray-600 px-4 py-2">
+									{isZh ? '构成 Agent 记忆，显示历史步骤' : 'Forms agent memory, displays history'}
+								</td>
+								<td className="border border-gray-300 dark:border-gray-600 px-4 py-2">
+									{isZh
+										? '实时 UI 反馈（如 loading 状态）'
+										: 'Real-time UI feedback (e.g., loading state)'}
+								</td>
+							</tr>
+						</tbody>
+					</table>
+				</div>
+			</section>
+
+			{/* All Events */}
+			<section className="mb-10">
+				<Heading id="all-events">{isZh ? '所有事件' : 'All Events'}</Heading>
+				<APIReference
+					properties={[
+						{
+							name: 'statuschange',
+							type: 'Event',
+							description: isZh
+								? 'Agent 状态变化 (idle → running → completed/error/stopped)'
+								: 'Agent status changes (idle → running → completed/error/stopped)',
+						},
+						{
+							name: 'historychange',
+							type: 'Event',
+							description: isZh
+								? '历史事件更新，读取 agent.history 获取完整历史'
+								: 'History updated, read agent.history for full history',
+						},
+						{
+							name: 'activity',
+							type: 'CustomEvent<AgentActivity>',
+							description: isZh
+								? '实时活动反馈：thinking, executing, executed, retrying, error'
+								: 'Real-time activity: thinking, executing, executed, retrying, error',
+						},
+						{
+							name: 'dispose',
+							type: 'Event',
+							description: isZh ? 'Agent 被销毁' : 'Agent is disposed',
+						},
+					]}
+				/>
+			</section>
+
+			{/* HistoricalEvent Types */}
+			<section className="mb-10">
+				<Heading id="historicalevent">HistoricalEvent</Heading>
+				<p className="text-gray-600 dark:text-gray-400 mb-4">
+					{isZh ? 'agent.history 数组中的事件类型：' : 'Event types in agent.history array:'}
+				</p>
+				<CodeEditor
+					language="typescript"
+					code={`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 }`}
+				/>
+			</section>
+
+			{/* AgentActivity Types */}
+			<section className="mb-10">
+				<Heading id="agentactivity">AgentActivity</Heading>
+				<p className="text-gray-600 dark:text-gray-400 mb-4">
+					{isZh ? 'activity 事件的 detail 类型：' : 'The detail type of activity events:'}
+				</p>
+				<CodeEditor
+					language="typescript"
+					code={`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 }`}
+				/>
+			</section>
+
+			<APIDivider title={isZh ? 'React 示例' : 'React Example'} />
+
+			{/* React Hooks Example */}
+			<section className="mb-10">
+				<Heading id="using-react-hooks">{isZh ? '使用 React Hooks' : 'Using React Hooks'}</Heading>
+				<p className="text-gray-600 dark:text-gray-400 mb-4">
+					{isZh ? '监听事件并更新 React 状态：' : 'Listen to events and update React state:'}
+				</p>
+				<CodeEditor
+					language="tsx"
+					code={`function useAgent(agent: PageAgentCore) {
+  const [status, setStatus] = useState(agent.status)
+  const [history, setHistory] = useState(agent.history)
+  const [activity, setActivity] = useState<AgentActivity | null>(null)
+
+  useEffect(() => {
+    const onStatus = () => setStatus(agent.status)
+    const onHistory = () => setHistory([...agent.history])
+    const onActivity = (e: Event) => setActivity((e as CustomEvent).detail)
+
+    agent.addEventListener('statuschange', onStatus)
+    agent.addEventListener('historychange', onHistory)
+    agent.addEventListener('activity', onActivity)
+
+    return () => {
+      agent.removeEventListener('statuschange', onStatus)
+      agent.removeEventListener('historychange', onHistory)
+      agent.removeEventListener('activity', onActivity)
+    }
+  }, [agent])
+
+  return { status, history, activity }
+}`}
+				/>
+			</section>
+
+			<APIDivider title={isZh ? '完整组装示例' : 'Complete Assembly Example'} />
+
+			{/* Assembly Example */}
+			<section className="mb-10">
+				<Heading id="assembling-core-controller-custom-ui">
+					{isZh ? '组装 Core + Controller + 自定义 UI' : 'Assembling Core + Controller + Custom UI'}
+				</Heading>
+				<p className="text-gray-600 dark:text-gray-400 mb-4">
+					{isZh
+						? '参考内置 PageAgent 的实现方式，用自定义 UI 替换 Panel：'
+						: 'Following the built-in PageAgent pattern, replace Panel with custom UI:'}
+				</p>
+				<CodeEditor
+					language="typescript"
+					code={`import { PageAgentCore } from '@page-agent/core'
+import { PageController } from '@page-agent/page-controller'
+
+// 1. Create PageController
+const pageController = new PageController({ enableMask: true })
+
+// 2. Create PageAgentCore with controller
+const agent = new PageAgentCore({
+  pageController,
+  baseURL: 'https://api.openai.com/v1',
+  apiKey: 'your-api-key',
+  model: 'gpt-5.2',
+})
+
+// 3. Mount your custom UI
+const root = createRoot(document.getElementById('my-ui')!)
+root.render(<MyAgentUI agent={agent} />)
+
+// 4. Handle user input (optional)
+//    options.signal aborts when the task is stopped or disposed
+agent.onAskUser = async (question, options) => window.prompt(question) || ''
+
+// 5. Execute task
+await agent.execute('Fill the form with test data')
+
+// 6. Cleanup
+agent.dispose()`}
+				/>
+			</section>
+		</div>
+	)
+}
diff --git a/packages/website/src/pages/docs/advanced/page-agent-core/page.tsx b/packages/website/src/pages/docs/advanced/page-agent-core/page.tsx
new file mode 100644
index 0000000..d5166f3
--- /dev/null
+++ b/packages/website/src/pages/docs/advanced/page-agent-core/page.tsx
@@ -0,0 +1,485 @@
+import { Link } from 'wouter'
+
+import { APIDivider, APIReference, TypeRef } from '@/components/APIReference'
+import CodeEditor from '@/components/CodeEditor'
+import { Heading } from '@/components/Heading'
+import { useLanguage } from '@/i18n/context'
+
+export default function PageAgentCoreDocs() {
+	const { isZh } = useLanguage()
+
+	return (
+		<div>
+			<h1 className="text-4xl font-bold mb-6">PageAgentCore</h1>
+
+			<p className="text-xl text-gray-600 dark:text-gray-300 mb-8 leading-relaxed">
+				{isZh
+					? 'PageAgentCore 是不带 UI 的核心 Agent 类。用于需要自定义 UI 或无头运行的场景。'
+					: 'PageAgentCore is the core Agent class without UI. Use it for custom UI or headless scenarios.'}
+			</p>
+
+			{/* When to use */}
+			<section className="mb-10">
+				<Heading id="when-to-use-pageagentcore">
+					{isZh ? '何时使用 PageAgentCore' : 'When to Use PageAgentCore'}
+				</Heading>
+				<ul className="list-disc list-inside text-gray-600 dark:text-gray-400 space-y-2">
+					<li>{isZh ? '需要自定义 UI 界面' : 'Need a custom UI interface'}</li>
+					<li>{isZh ? '在自动化测试中无头运行' : 'Running headless in automated tests'}</li>
+					<li>
+						{isZh
+							? '在非浏览器环境运行（需自定义 PageController）'
+							: 'Running in non-browser environments (requires custom PageController)'}
+					</li>
+					<li>
+						{isZh
+							? '将 PageAgent 嵌入其他 Agent 系统'
+							: 'Embedding PageAgent in other agent systems'}
+					</li>
+				</ul>
+			</section>
+
+			{/* Basic Usage */}
+			<section className="mb-10">
+				<Heading id="basic-usage">{isZh ? '基本用法' : 'Basic Usage'}</Heading>
+				<CodeEditor
+					language="typescript"
+					code={`import { PageAgentCore } from '@page-agent/core'
+import { PageController } from '@page-agent/page-controller'
+
+const agent = new PageAgentCore({
+  pageController: new PageController({ enableMask: true }),
+  baseURL: 'https://api.openai.com/v1',
+  apiKey: 'your-api-key',
+  model: 'gpt-5.2',
+})
+
+// Listen to events for UI display
+agent.addEventListener('statuschange', () => {
+  console.log('Status:', agent.status)
+})
+
+agent.addEventListener('activity', (e) => {
+  const activity = (e as CustomEvent).detail
+  console.log('Activity:', activity.type)
+})
+
+// Execute task
+const result = await agent.execute('Fill in the form with test data')`}
+				/>
+			</section>
+
+			<APIDivider title={isZh ? '配置' : 'Configuration'} />
+
+			{/* Configuration */}
+			<section className="mb-10">
+				<Heading id="configuration">PageAgentCoreConfig</Heading>
+				<p className="text-gray-600 dark:text-gray-400 mb-4">
+					{isZh
+						? 'PageAgentCoreConfig = AgentConfig & { pageController: PageController }。AgentConfig 包含以下配置项：'
+						: 'PageAgentCoreConfig = AgentConfig & { pageController: PageController }. AgentConfig contains the following options:'}
+				</p>
+
+				{/* PageController */}
+				<h3 className="text-lg font-semibold mt-6 mb-3 text-gray-800 dark:text-gray-200">
+					PageController
+				</h3>
+				<APIReference
+					properties={[
+						{
+							name: 'pageController',
+							type: 'PageController',
+							required: true,
+							description: isZh ? (
+								<>
+									<Link
+										href="/advanced/page-controller"
+										className="text-blue-600 dark:text-blue-400 hover:underline"
+									>
+										PageController
+									</Link>{' '}
+									实例，用于 DOM 操作和元素交互。
+								</>
+							) : (
+								<>
+									<Link
+										href="/advanced/page-controller"
+										className="text-blue-600 dark:text-blue-400 hover:underline"
+									>
+										PageController
+									</Link>{' '}
+									instance for DOM operations and element interaction.
+								</>
+							),
+						},
+					]}
+				/>
+
+				{/* LLM Config */}
+				<h3 className="text-lg font-semibold mt-6 mb-3 text-gray-800 dark:text-gray-200">
+					{isZh ? 'LLM 配置' : 'LLM Config'}
+				</h3>
+				<APIReference
+					properties={[
+						{
+							name: 'baseURL',
+							type: 'string',
+							required: true,
+							description: isZh
+								? 'LLM API 的基础 URL（如 https://api.openai.com/v1）'
+								: 'Base URL of the LLM API (e.g., https://api.openai.com/v1)',
+						},
+						{
+							name: 'model',
+							type: 'string',
+							required: true,
+							description: isZh
+								? '模型名称（如 gpt-5.2, anthropic/claude-4.5-haiku）'
+								: 'Model name (e.g., gpt-5.2, anthropic/claude-4.5-haiku)',
+						},
+						{
+							name: 'apiKey',
+							type: 'string',
+							required: false,
+							description: 'LLM AK',
+						},
+						{
+							name: 'maxRetries',
+							type: 'number',
+							defaultValue: '3',
+							description: isZh ? 'API 调用失败时的最大重试次数' : 'Maximum retries on API failure',
+						},
+						{
+							name: 'transformRequestBody',
+							type: '(requestBody) => Record<string, unknown> | undefined',
+							description: isZh ? (
+								<>
+									在请求发送前转换最终 request body。可用于处理供应商特定的缓存提示或私有参数。查看{' '}
+									<Link
+										href="/features/models#prompt-caching"
+										className="text-blue-600 dark:text-blue-400 hover:underline"
+									>
+										主动缓存示例
+									</Link>
+									。
+								</>
+							) : (
+								<>
+									Transform the final request body before sending it. Useful for provider-specific
+									cache hints or private request parameters. See{' '}
+									<Link
+										href="/features/models#prompt-caching"
+										className="text-blue-600 dark:text-blue-400 hover:underline"
+									>
+										prompt caching examples
+									</Link>
+									.
+								</>
+							),
+						},
+						{
+							name: 'disableNamedToolChoice',
+							type: 'boolean',
+							defaultValue: 'false',
+							description: isZh
+								? '禁用命名 tool_choice，始终使用 "required" 字符串。适用于不支持 tool_choice 对象格式的 LLM 服务。'
+								: 'Disable named tool_choice, always use "required" string. For LLM services that don\'t support the object format of tool_choice.',
+						},
+						{
+							name: 'customFetch',
+							type: 'typeof fetch',
+							description: isZh
+								? '自定义 fetch 函数，用于定制 headers、credentials、代理等'
+								: 'Custom fetch function for customizing headers, credentials, proxy, etc.',
+						},
+					]}
+				/>
+
+				{/* Agent Config */}
+				<h3 className="text-lg font-semibold mt-6 mb-3 text-gray-800 dark:text-gray-200">
+					{isZh ? 'Agent 配置' : 'Agent Config'}
+				</h3>
+				<APIReference
+					properties={[
+						{
+							name: 'language',
+							type: "'en-US' | 'zh-CN'",
+							defaultValue: "'en-US'",
+							description: isZh ? 'Agent 输出语言' : 'Agent output language',
+						},
+						{
+							name: 'maxSteps',
+							type: 'number',
+							defaultValue: '40',
+							description: isZh ? '每个任务的最大步骤数' : 'Maximum number of steps per task',
+						},
+						{
+							name: 'customTools',
+							type: 'Record<string, PageAgentTool | null>',
+							status: 'experimental',
+							description: isZh
+								? '自定义工具，可扩展或覆盖内置工具。设为 null 可移除工具。'
+								: 'Custom tools to extend or override built-in tools. Set to null to remove a tool.',
+						},
+						{
+							name: 'instructions',
+							type: 'InstructionsConfig',
+							description: isZh
+								? '指导 Agent 行为的指令配置，见下方类型定义'
+								: 'Instructions to guide agent behavior, see type definition below',
+						},
+						{
+							name: 'transformPageContent',
+							type: '(content: string) => string | Promise<string>',
+							description: isZh
+								? '发送给 LLM 前转换页面内容，可用于数据脱敏'
+								: 'Transform page content before sending to LLM, useful for data masking',
+						},
+						{
+							name: 'customSystemPrompt',
+							type: 'string',
+							status: 'experimental',
+							description: isZh
+								? '完全覆盖默认系统提示词。谨慎使用。'
+								: 'Completely override the default system prompt. Use with caution.',
+						},
+						{
+							name: 'experimentalScript\nExecutionTool',
+							type: 'boolean',
+							defaultValue: 'false',
+							status: 'experimental',
+							description: isZh
+								? '启用实验性 JavaScript 执行工具'
+								: 'Enable experimental JavaScript execution tool',
+						},
+						{
+							name: 'experimentalLlmsTxt',
+							type: 'boolean',
+							defaultValue: 'false',
+							status: 'experimental',
+							description: isZh
+								? '从当前站点根目录获取 /llms.txt 并作为上下文提供给 LLM'
+								: 'Fetch /llms.txt from site origin and include as LLM context',
+						},
+					]}
+				/>
+
+				{/* Lifecycle Hooks */}
+				<h3 className="text-lg font-semibold mt-6 mb-3 text-gray-800 dark:text-gray-200">
+					{isZh ? '生命周期钩子' : 'Lifecycle Hooks'}
+					<span className="ml-2 text-xs font-normal text-amber-600 dark:text-amber-400">
+						experimental
+					</span>
+				</h3>
+				<div className="bg-amber-50 dark:bg-amber-900/20 border border-amber-200 dark:border-amber-800 rounded-lg p-4 mb-4">
+					<p className="text-amber-800 dark:text-amber-200 text-sm">
+						{isZh
+							? '这些接口高度实验性，可能在未来版本中发生变化。钩子中抛出的错误会使任务失败并从 execute() 抛出；如不希望影响任务，请在钩子内部自行捕获。'
+							: 'These APIs are highly experimental and may change in future versions. Errors thrown from hooks fail the run and propagate from execute(); catch errors inside the hook if the task should not be affected.'}
+					</p>
+				</div>
+				<APIReference
+					properties={[
+						{
+							name: 'onBeforeStep',
+							type: '(agent, stepCount) => void | Promise<void>',
+							description: isZh ? '每个步骤执行前调用' : 'Called before each step execution',
+						},
+						{
+							name: 'onAfterStep',
+							type: '(agent, history) => void | Promise<void>',
+							description: isZh ? '每个步骤执行后调用' : 'Called after each step execution',
+						},
+						{
+							name: 'onBeforeTask',
+							type: '(agent) => void | Promise<void>',
+							description: isZh ? '任务开始前调用' : 'Called before task starts',
+						},
+						{
+							name: 'onAfterTask',
+							type: '(agent, result) => void | Promise<void>',
+							description: isZh ? '任务结束后调用' : 'Called after task ends',
+						},
+						{
+							name: 'onDispose',
+							type: '(agent, reason?) => void',
+							description: isZh ? 'Agent 销毁时调用' : 'Called when agent is disposed',
+						},
+					]}
+				/>
+			</section>
+
+			<APIDivider title={isZh ? '属性与方法' : 'Properties & Methods'} />
+
+			{/* Properties */}
+			<section className="mb-10">
+				<Heading id="properties">{isZh ? '属性' : 'Properties'}</Heading>
+				<APIReference
+					properties={[
+						{
+							name: 'status',
+							type: "'idle' | 'running' | 'completed' | 'error' | 'stopped'",
+							description: isZh ? '当前 Agent 执行状态' : 'Current agent execution status',
+						},
+						{
+							name: 'history',
+							type: 'HistoricalEvent[]',
+							description: isZh
+								? '历史事件数组，构成 Agent 的记忆'
+								: 'Array of historical events, forms agent memory',
+						},
+						{
+							name: 'task',
+							type: 'string',
+							description: isZh ? '当前正在执行的任务' : 'Current task being executed',
+						},
+						{
+							name: 'pageController',
+							type: 'PageController',
+							description: isZh
+								? 'PageController 实例，用于 DOM 操作'
+								: 'PageController instance for DOM operations',
+						},
+						{
+							name: 'tools',
+							type: 'Map<string, PageAgentTool>',
+							description: isZh ? '可用工具的 Map' : 'Map of available tools',
+						},
+						{
+							name: 'onAskUser',
+							type: '(question: string, options?: { signal: AbortSignal }) => Promise<string>',
+							description: isZh
+								? '当 agent 需要向用户提问时调用。未设置则禁用 `ask_user` 工具。实现应在 options.signal 触发 abort 时 reject promise。'
+								: 'Called when the agent needs to ask the user questions. If unset, the `ask_user` tool will be disabled. Implementations should reject the promise when options.signal aborts.',
+						},
+					]}
+				/>
+			</section>
+
+			{/* Methods */}
+			<section className="mb-10">
+				<Heading id="methods">{isZh ? '方法' : 'Methods'}</Heading>
+				<APIReference
+					variant="methods"
+					properties={[
+						{
+							name: 'execute(task)',
+							type: 'Promise<ExecutionResult>',
+							description: isZh
+								? '执行任务并返回结果（包含 success、data 和 history 字段）。若已有任务在运行则抛出错误——不支持并发执行。'
+								: 'Execute a task and return result (contains success, data, and history fields). Throws if a task is already running — concurrent execution is not supported.',
+						},
+						{
+							name: 'stop()',
+							type: 'Promise<void>',
+							description: isZh
+								? '停止当前任务，并在任务完全结束后 resolve。Agent 仍可复用。'
+								: 'Stop the current task; resolves once the run has fully settled. Agent remains reusable.',
+						},
+						{
+							name: 'dispose()',
+							type: 'void',
+							description: isZh
+								? '销毁 Agent 并清理资源'
+								: 'Dispose the agent and clean up resources',
+						},
+					]}
+				/>
+			</section>
+
+			{/* Events */}
+			<section className="mb-10">
+				<Heading id="events">{isZh ? '事件' : 'Events'}</Heading>
+				<p className="text-gray-600 dark:text-gray-400 mb-4">
+					{isZh ? (
+						<>
+							PageAgentCore 继承自 <TypeRef>EventTarget</TypeRef>，提供以下事件：
+						</>
+					) : (
+						<>
+							PageAgentCore extends <TypeRef>EventTarget</TypeRef> and provides the following
+							events:
+						</>
+					)}
+				</p>
+				<APIReference
+					properties={[
+						{
+							name: 'statuschange',
+							type: 'Event',
+							description: isZh
+								? 'Agent 状态变化时触发 (idle → running → completed/error/stopped)'
+								: 'Fired when agent status changes (idle → running → completed/error/stopped)',
+						},
+						{
+							name: 'historychange',
+							type: 'Event',
+							description: isZh
+								? '历史事件更新时触发（持久化事件，构成 Agent 记忆）'
+								: 'Fired when history events are updated (persistent, part of agent memory)',
+						},
+						{
+							name: 'activity',
+							type: 'CustomEvent<AgentActivity>',
+							description: isZh
+								? '实时活动反馈（短暂状态，仅用于 UI）。类型包括：thinking, executing, executed, retrying, error'
+								: 'Real-time activity feedback (transient, UI only). Types: thinking, executing, executed, retrying, error',
+						},
+						{
+							name: 'dispose',
+							type: 'Event',
+							description: isZh ? 'Agent 被销毁时触发' : 'Fired when agent is disposed',
+						},
+					]}
+				/>
+			</section>
+
+			<APIDivider title={isZh ? '类型定义' : 'Type Definitions'} />
+
+			{/* ExecutionResult */}
+			<section className="mb-10">
+				<Heading id="executionresult">ExecutionResult</Heading>
+				<CodeEditor
+					language="typescript"
+					code={`interface ExecutionResult {
+  success: boolean
+  data: string
+  history: HistoricalEvent[]
+}`}
+				/>
+			</section>
+
+			{/* AgentActivity */}
+			<section className="mb-10">
+				<Heading id="agentactivity">AgentActivity</Heading>
+				<CodeEditor
+					language="typescript"
+					code={`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 }`}
+				/>
+			</section>
+
+			{/* InstructionsConfig */}
+			<section className="mb-10">
+				<Heading id="instructionsconfig">InstructionsConfig</Heading>
+				<CodeEditor
+					language="typescript"
+					code={`interface InstructionsConfig {
+  /** Global system-level instructions, applied to all tasks */
+  system?: string
+
+  /**
+   * Dynamic page-level instructions callback.
+   * Called before each step to get instructions for the current page.
+   */
+  getPageInstructions?: (url: string) => string | undefined
+}`}
+				/>
+			</section>
+		</div>
+	)
+}
diff --git a/packages/website/src/pages/docs/advanced/page-agent/page.tsx b/packages/website/src/pages/docs/advanced/page-agent/page.tsx
new file mode 100644
index 0000000..a0e2471
--- /dev/null
+++ b/packages/website/src/pages/docs/advanced/page-agent/page.tsx
@@ -0,0 +1,224 @@
+import { Link } from 'wouter'
+
+import CodeEditor from '@/components/CodeEditor'
+import { Heading } from '@/components/Heading'
+import { useLanguage } from '@/i18n/context'
+
+export default function PageAgentDocs() {
+	const { isZh } = useLanguage()
+
+	return (
+		<div>
+			<h1 className="text-4xl font-bold mb-6">PageAgent</h1>
+
+			<p className="text-xl text-gray-600 dark:text-gray-300 mb-8 leading-relaxed">
+				{isZh
+					? 'PageAgent 是带有内置 UI 面板的完整 Agent 类。它继承自 PageAgentCore，并自动创建交互面板和 PageController。'
+					: 'PageAgent is the complete Agent class with built-in UI panel. It extends PageAgentCore and automatically creates an interactive panel and PageController.'}
+			</p>
+
+			{/* When to use */}
+			<section className="mb-10">
+				<Heading id="when-to-use-pageagent">
+					{isZh ? '何时使用 PageAgent' : 'When to Use PageAgent'}
+				</Heading>
+				<p className="text-gray-600 dark:text-gray-400 mb-4">
+					{isZh
+						? '在大多数场景下，你应该使用 PageAgent。它提供了开箱即用的完整体验：'
+						: 'In most cases, you should use PageAgent. It provides a complete out-of-the-box experience:'}
+				</p>
+				<ul className="list-disc list-inside text-gray-600 dark:text-gray-400 space-y-2 mb-6">
+					<li>
+						{isZh
+							? '自动创建 PageController，处理 DOM 提取和元素操作'
+							: 'Automatically creates PageController for DOM extraction and element actions'}
+					</li>
+					<li>
+						{isZh
+							? '内置 UI 面板，显示任务进度、Agent 思考过程和操作结果'
+							: 'Built-in UI panel showing task progress, agent thinking, and action results'}
+					</li>
+					<li>
+						{isZh
+							? '支持 ask_user 工具，Agent 可以向用户提问'
+							: 'Supports ask_user tool for agent to ask questions to users'}
+					</li>
+				</ul>
+			</section>
+
+			{/* Basic Usage */}
+			<section className="mb-10">
+				<Heading id="basic-usage">{isZh ? '基本用法' : 'Basic Usage'}</Heading>
+				<CodeEditor
+					language="typescript"
+					code={`import { PageAgent } from 'page-agent'
+
+const agent = new PageAgent({
+  // LLM Configuration (required)
+  baseURL: 'https://api.openai.com/v1',
+  apiKey: 'your-api-key',
+  model: 'gpt-5.2',
+  
+  // Optional settings
+  language: 'en-US',
+})
+
+// Execute a task
+const result = await agent.execute('Click the login button')
+
+console.log(result.success) // true or false
+console.log(result.data)    // Task result description
+console.log(result.history) // Full execution history`}
+				/>
+			</section>
+
+			{/* Class Definition */}
+			<section className="mb-10">
+				<Heading id="class-definition">{isZh ? '类定义' : 'Class Definition'}</Heading>
+				<CodeEditor
+					language="typescript"
+					code={`class PageAgent extends PageAgentCore {
+  panel: Panel
+  pageController: PageController
+  constructor(config: PageAgentConfig)
+}`}
+				/>
+				<p className="text-gray-600 dark:text-gray-400 mt-4">
+					{isZh ? (
+						<>
+							PageAgent 继承自{' '}
+							<Link
+								href="/advanced/page-agent-core"
+								className="text-blue-600 dark:text-blue-400 hover:underline"
+							>
+								PageAgentCore
+							</Link>
+							，所有核心方法和事件都可用。配置项合并了{' '}
+							<Link
+								href="/advanced/page-agent-core#configuration"
+								className="text-blue-600 dark:text-blue-400 hover:underline"
+							>
+								AgentConfig
+							</Link>{' '}
+							、 PanelConfig 和{' '}
+							<Link
+								href="/advanced/page-controller#configuration"
+								className="text-blue-600 dark:text-blue-400 hover:underline"
+							>
+								PageControllerConfig
+							</Link>
+							。
+						</>
+					) : (
+						<>
+							PageAgent extends{' '}
+							<Link
+								href="/advanced/page-agent-core"
+								className="text-blue-600 dark:text-blue-400 hover:underline"
+							>
+								PageAgentCore
+							</Link>
+							. All core methods and events are available. Config merges{' '}
+							<Link
+								href="/advanced/page-agent-core#configuration"
+								className="text-blue-600 dark:text-blue-400 hover:underline"
+							>
+								AgentConfig
+							</Link>{' '}
+							, PanelConfig, and{' '}
+							<Link
+								href="/advanced/page-controller#configuration"
+								className="text-blue-600 dark:text-blue-400 hover:underline"
+							>
+								PageControllerConfig
+							</Link>
+							.
+						</>
+					)}
+				</p>
+			</section>
+
+			{/* Panel */}
+			<section className="mb-10">
+				<Heading id="panel">{isZh ? 'UI 面板' : 'UI Panel'}</Heading>
+				<p className="text-gray-600 dark:text-gray-400 mb-4">
+					{isZh
+						? 'PageAgent 自动创建一个 Panel 实例。你可以通过 panel 属性控制 UI：'
+						: 'PageAgent automatically creates a Panel instance. You can control the UI via the panel property:'}
+				</p>
+				<CodeEditor
+					language="typescript"
+					code={`// Show/hide the panel
+agent.panel.show()
+agent.panel.hide()
+
+// Expand/collapse history view
+agent.panel.expand()
+agent.panel.collapse()
+
+// Reset panel state
+agent.panel.reset()
+
+// Dispose panel (called automatically when agent disposes)
+agent.panel.dispose()`}
+				/>
+			</section>
+
+			{/* Comparison with PageAgentCore */}
+			<section className="mb-10">
+				<Heading id="pageagent-vs-pageagentcore">
+					{isZh ? 'PageAgent vs PageAgentCore' : 'PageAgent vs PageAgentCore'}
+				</Heading>
+				<div className="overflow-hidden rounded-lg border border-gray-200 dark:border-gray-700">
+					<table className="w-full text-sm">
+						<thead>
+							<tr className="bg-gray-50 dark:bg-gray-800/50">
+								<th className="px-4 py-3 text-left font-medium text-gray-600 dark:text-gray-300"></th>
+								<th className="px-4 py-3 text-center font-medium text-gray-600 dark:text-gray-300">
+									PageAgent
+								</th>
+								<th className="px-4 py-3 text-center font-medium text-gray-600 dark:text-gray-300">
+									PageAgentCore
+								</th>
+							</tr>
+						</thead>
+						<tbody className="divide-y divide-gray-100 dark:divide-gray-800">
+							<tr className="bg-white dark:bg-gray-900">
+								<td className="px-4 py-3 text-gray-600 dark:text-gray-400">
+									{isZh ? 'UI 面板' : 'UI Panel'}
+								</td>
+								<td className="px-4 py-3 text-center text-green-600 dark:text-green-400">✓</td>
+								<td className="px-4 py-3 text-center text-gray-400 dark:text-gray-600">-</td>
+							</tr>
+							<tr className="bg-white dark:bg-gray-900">
+								<td className="px-4 py-3 text-gray-600 dark:text-gray-400">
+									{isZh ? '自动创建 PageController' : 'Auto-creates PageController'}
+								</td>
+								<td className="px-4 py-3 text-center text-green-600 dark:text-green-400">✓</td>
+								<td className="px-4 py-3 text-center text-gray-400 dark:text-gray-600">-</td>
+							</tr>
+							<tr className="bg-white dark:bg-gray-900">
+								<td className="px-4 py-3 text-gray-600 dark:text-gray-400">
+									{isZh ? 'Headless 模式' : 'Headless Mode'}
+								</td>
+								<td className="px-4 py-3 text-center text-gray-400 dark:text-gray-600">-</td>
+								<td className="px-4 py-3 text-center text-green-600 dark:text-green-400">✓</td>
+							</tr>
+							<tr className="bg-white dark:bg-gray-900">
+								<td className="px-4 py-3 text-gray-600 dark:text-gray-400">
+									{isZh ? '适用场景' : 'Use Case'}
+								</td>
+								<td className="px-4 py-3 text-center text-gray-600 dark:text-gray-400">
+									{isZh ? '网页集成' : 'Web integration'}
+								</td>
+								<td className="px-4 py-3 text-center text-gray-600 dark:text-gray-400">
+									{isZh ? '自定义 UI / 无头' : 'Custom UI / Headless'}
+								</td>
+							</tr>
+						</tbody>
+					</table>
+				</div>
+			</section>
+		</div>
+	)
+}
diff --git a/packages/website/src/pages/docs/advanced/page-controller/page.tsx b/packages/website/src/pages/docs/advanced/page-controller/page.tsx
new file mode 100644
index 0000000..b1d781d
--- /dev/null
+++ b/packages/website/src/pages/docs/advanced/page-controller/page.tsx
@@ -0,0 +1,294 @@
+import { Link } from 'wouter'
+
+import { APIDivider, APIReference } from '@/components/APIReference'
+import CodeEditor from '@/components/CodeEditor'
+import { Heading } from '@/components/Heading'
+import { useLanguage } from '@/i18n/context'
+
+export default function PageControllerDocs() {
+	const { isZh } = useLanguage()
+
+	return (
+		<div>
+			<h1 className="text-4xl font-bold mb-6">PageController</h1>
+
+			<p className="text-xl text-gray-600 dark:text-gray-300 mb-8 leading-relaxed">
+				{isZh
+					? 'PageController 负责 DOM 提取和元素交互，独立于 LLM。它将页面状态结构化为 LLM 可消费的格式，并执行元素级操作。'
+					: 'PageController handles DOM extraction and element interaction, independent of LLM. It structures page state into LLM-consumable format and executes element-level actions.'}
+			</p>
+
+			{/* Basic Usage */}
+			<section className="mb-10">
+				<Heading id="basic-usage">{isZh ? '基本用法' : 'Basic Usage'}</Heading>
+				<p className="text-gray-600 dark:text-gray-400 mb-4">
+					{isZh
+						? 'PageAgent 接受 PageController 配置项：'
+						: 'PageAgent accepts PageController options:'}
+				</p>
+				<CodeEditor
+					language="typescript"
+					code={`import { PageAgent } from 'page-agent'
+
+const agent = new PageAgent({
+  baseURL: 'https://api.openai.com/v1',
+  apiKey: 'your-api-key',
+  model: 'gpt-5.2',
+
+  // PageController options
+  enableMask: true,
+  viewportExpansion: 0,
+})`}
+				/>
+				<p className="text-gray-600 dark:text-gray-400 mt-4">
+					{isZh
+						? 'PageAgentCore 接受 PageController 实例：'
+						: 'PageAgentCore accepts a PageController instance:'}
+				</p>
+				<CodeEditor
+					language="typescript"
+					code={`import { PageAgentCore } from '@page-agent/core'
+import { PageController } from '@page-agent/page-controller'
+
+const pageController = new PageController({
+  enableMask: true,
+  viewportExpansion: -1,  // extract full page
+})
+
+const agent = new PageAgentCore({
+  pageController,
+  baseURL: 'https://api.openai.com/v1',
+  apiKey: 'your-api-key',
+  model: 'gpt-5.2',
+})`}
+				/>
+			</section>
+
+			<APIDivider title={isZh ? '配置' : 'Configuration'} />
+
+			{/* Configuration */}
+			<section className="mb-10">
+				<Heading id="configuration">PageControllerConfig</Heading>
+				<APIReference
+					properties={[
+						{
+							name: 'enableMask',
+							type: 'boolean',
+							defaultValue: 'false',
+							description: isZh
+								? '启用视觉遮罩覆盖层，在自动化期间阻止用户操作页面。通过 PageAgent 创建时默认为 true。'
+								: 'Enable visual mask overlay that blocks user interaction during automation. Defaults to true when created via PageAgent.',
+						},
+						{
+							name: 'viewportExpansion',
+							type: 'number',
+							defaultValue: '0',
+							description: isZh
+								? '向视口外扩展提取的像素数。设为 -1 表示提取整个页面。'
+								: 'Pixels to expand extraction beyond viewport. Set to -1 to extract the entire page.',
+						},
+						{
+							name: 'interactiveBlacklist',
+							type: '(Element | (() => Element))[]',
+							description: isZh
+								? '要排除的交互元素列表。支持元素引用或返回元素的函数（延迟求值）。'
+								: 'Elements to exclude from interaction. Supports element references or functions returning elements (lazy evaluation).',
+						},
+						{
+							name: 'interactiveWhitelist',
+							type: '(Element | (() => Element))[]',
+							description: isZh
+								? '要强制包含的交互元素列表。支持元素引用或返回元素的函数。'
+								: 'Elements to force include for interaction. Supports element references or functions returning elements.',
+						},
+						{
+							name: 'includeAttributes',
+							type: 'string[]',
+							description: isZh
+								? '在 DOM 提取中包含的额外 HTML 属性。支持通配符 *（如 data-* 匹配所有 data- 开头的属性）。默认已包含常见属性如 role, aria-label 等。'
+								: 'Additional HTML attributes to include in DOM extraction. Supports wildcard * (e.g. data-* matches all data- prefixed attributes). Common attributes like role, aria-label are included by default.',
+						},
+						{
+							name: 'keepSemanticTags',
+							type: 'boolean',
+							defaultValue: 'false',
+							description: isZh
+								? '在简化输出中保留语义标签（如 nav, main, header, footer, aside 等），即使它们不可交互。帮助 LLM 理解页面结构。'
+								: 'Preserve semantic landmark tags (e.g. nav, main, header, footer, aside) in dehydrated output even if not interactive. Helps LLM understand page structure.',
+						},
+					]}
+				/>
+			</section>
+
+			<APIDivider title={isZh ? '方法' : 'Methods'} />
+
+			{/* Methods */}
+			<section className="mb-10">
+				<Heading id="methods">{isZh ? '方法' : 'Methods'}</Heading>
+
+				<h3 className="text-lg font-semibold mt-6 mb-3">{isZh ? '状态查询' : 'State Queries'}</h3>
+				<APIReference
+					variant="methods"
+					properties={[
+						{
+							name: 'getBrowserState()',
+							type: 'Promise<BrowserState>',
+							description: isZh
+								? '获取结构化的浏览器状态（URL、标题、简化 HTML 等），自动调用 updateTree() 刷新 DOM。这是 Agent 在每步使用的主要方法。'
+								: 'Get structured browser state (URL, title, simplified HTML, etc.), automatically calls updateTree() to refresh DOM. This is the primary method the agent uses each step.',
+						},
+						{
+							name: 'updateTree()',
+							type: 'Promise<string>',
+							description: isZh
+								? '刷新 DOM 树并返回简化 HTML。通常不需要手动调用 —— getBrowserState() 会自动调用。'
+								: 'Refresh DOM tree and return simplified HTML. Usually not needed manually — getBrowserState() calls it automatically.',
+						},
+						{
+							name: 'getCurrentUrl()',
+							type: 'Promise<string>',
+							description: isZh ? '获取当前页面 URL。' : 'Get current page URL.',
+						},
+					]}
+				/>
+
+				<h3 className="text-lg font-semibold mt-6 mb-3">{isZh ? '元素操作' : 'Element Actions'}</h3>
+				<APIReference
+					variant="methods"
+					properties={[
+						{
+							name: 'clickElement(index)',
+							type: 'Promise<ActionResult>',
+							description: isZh
+								? '按索引点击元素。索引来自简化 HTML 中的 [N] 标记。'
+								: 'Click element by index. Index comes from [N] markers in simplified HTML.',
+						},
+						{
+							name: 'inputText(index, text)',
+							type: 'Promise<ActionResult>',
+							description: isZh ? '向输入框元素填入文本。' : 'Input text into a form element.',
+						},
+						{
+							name: 'selectOption(index, optionText)',
+							type: 'Promise<ActionResult>',
+							description: isZh ? '在下拉框中选择选项。' : 'Select option in a dropdown element.',
+						},
+						{
+							name: 'scroll(options)',
+							type: 'Promise<ActionResult>',
+							description: isZh
+								? '垂直滚动页面或指定元素。'
+								: 'Scroll page or specific element vertically.',
+						},
+						{
+							name: 'scrollHorizontally(options)',
+							type: 'Promise<ActionResult>',
+							description: isZh
+								? '水平滚动页面或指定元素。'
+								: 'Scroll page or specific element horizontally.',
+						},
+					]}
+				/>
+
+				<h3 className="text-lg font-semibold mt-6 mb-3">{isZh ? '遮罩控制' : 'Mask Control'}</h3>
+				<APIReference
+					variant="methods"
+					properties={[
+						{
+							name: 'showMask()',
+							type: 'Promise<void>',
+							description: isZh
+								? '显示视觉遮罩。需要 enableMask: true。'
+								: 'Show visual mask overlay. Requires enableMask: true.',
+						},
+						{
+							name: 'hideMask()',
+							type: 'Promise<void>',
+							description: isZh ? '隐藏视觉遮罩。' : 'Hide visual mask overlay.',
+						},
+					]}
+				/>
+
+				<h3 className="text-lg font-semibold mt-6 mb-3">{isZh ? '生命周期' : 'Lifecycle'}</h3>
+				<APIReference
+					variant="methods"
+					properties={[
+						{
+							name: 'dispose()',
+							type: 'void',
+							description: isZh
+								? '清理所有资源（DOM 高亮、遮罩等）。Agent 销毁时自动调用。'
+								: 'Clean up all resources (DOM highlights, mask, etc.). Called automatically when agent disposes.',
+						},
+					]}
+				/>
+			</section>
+
+			<APIDivider title={isZh ? '类型定义' : 'Type Definitions'} />
+
+			{/* BrowserState */}
+			<section className="mb-10">
+				<Heading id="browser-state">BrowserState</Heading>
+				<p className="text-gray-600 dark:text-gray-400 mb-4">
+					{isZh
+						? 'getBrowserState() 返回的结构化浏览器状态，直接用于构建 LLM prompt。'
+						: 'Structured browser state returned by getBrowserState(), used directly to build LLM prompts.'}
+				</p>
+				<CodeEditor
+					language="typescript"
+					code={`interface BrowserState {
+  url: string
+  title: string
+  header: string   // page info + scroll position
+  content: string  // simplified HTML of interactive elements
+  footer: string   // scroll hint
+}`}
+				/>
+			</section>
+
+			{/* ActionResult */}
+			<section className="mb-10">
+				<Heading id="action-result">ActionResult</Heading>
+				<CodeEditor
+					language="typescript"
+					code={`interface ActionResult {
+  success: boolean
+  message: string
+}`}
+				/>
+			</section>
+
+			{/* Custom PageController */}
+			<section className="mb-10">
+				<Heading id="custom-implementation">
+					{isZh ? '自定义实现' : 'Custom Implementation'}
+				</Heading>
+				<p className="text-gray-600 dark:text-gray-400 mb-4">
+					{isZh
+						? '在非浏览器环境（如 Puppeteer、Playwright），你可以实现自定义 PageController。需要实现 Agent 使用的核心方法：'
+						: 'In non-browser environments (e.g. Puppeteer, Playwright), you can implement a custom PageController. Implement the core methods used by the agent:'}
+				</p>
+				<CodeEditor
+					language="typescript"
+					code={`import { PageAgentCore } from '@page-agent/core'
+import type { PageController } from '@page-agent/page-controller'
+
+class PuppeteerPageController implements PageController {
+  async getBrowserState() { /* ... */ }
+  async clickElement(index: number) { /* ... */ }
+  async inputText(index: number, text: string) { /* ... */ }
+  async scroll(options: { down: boolean; numPages: number }) { /* ... */ }
+  // ... other methods
+}
+
+const agent = new PageAgentCore({
+  pageController: new PuppeteerPageController(),
+  baseURL: 'https://api.openai.com/v1',
+  apiKey: 'your-api-key',
+  model: 'gpt-5.2',
+})`}
+				/>
+			</section>
+		</div>
+	)
+}
diff --git a/packages/website/src/pages/docs/advanced/security-permissions/page.tsx b/packages/website/src/pages/docs/advanced/security-permissions/page.tsx
new file mode 100644
index 0000000..ac7824f
--- /dev/null
+++ b/packages/website/src/pages/docs/advanced/security-permissions/page.tsx
@@ -0,0 +1,89 @@
+import BetaNotice from '@/components/BetaNotice'
+import { Heading } from '@/components/Heading'
+import { useLanguage } from '@/i18n/context'
+
+export default function SecurityPermissions() {
+	const { isZh } = useLanguage()
+
+	return (
+		<div>
+			<BetaNotice />
+
+			<h1 className="text-4xl font-bold mb-6">{isZh ? '安全与权限' : 'Security & Permissions'}</h1>
+
+			<p className="text-xl text-gray-600 dark:text-gray-300 mb-8 leading-relaxed">
+				{isZh
+					? 'page-agent 提供多种安全机制，确保 AI 操作在可控范围内进行。'
+					: 'page-agent provides multiple security mechanisms to ensure AI operations stay within controlled boundaries.'}
+			</p>
+
+			<div className="space-y-6">
+				<section>
+					<Heading id="element-interaction-allowlist-blocklist" className="text-2xl font-bold mb-3">
+						{isZh ? '元素操作黑白名单' : 'Element Interaction Allowlist/Blocklist'}
+					</Heading>
+					<div className="space-y-3">
+						<div className="p-4 bg-red-50 dark:bg-red-900/20 rounded-lg">
+							<h3 className="text-lg font-semibold text-red-900 dark:text-red-300">
+								🚫 {isZh ? '操作黑名单' : 'Blocklist'}
+							</h3>
+							<p className="text-gray-600 dark:text-gray-300">
+								{isZh
+									? '禁止 AI 操作敏感元素，如删除按钮、支付按钮等。'
+									: 'Prevent AI from interacting with sensitive elements like delete buttons, payment buttons, etc.'}
+							</p>
+						</div>
+						<div className="p-4 bg-green-50 dark:bg-green-900/20 rounded-lg">
+							<h3 className="text-lg font-semibold text-green-900 dark:text-green-300">
+								✅ {isZh ? '操作白名单' : 'Allowlist'}
+							</h3>
+							<p className="text-gray-600 dark:text-gray-300">
+								{isZh
+									? '明确定义 AI 可以操作的元素范围。'
+									: 'Explicitly define which elements AI can interact with.'}
+							</p>
+						</div>
+					</div>
+				</section>
+
+				<section>
+					<Heading id="instruction-safety-constraints" className="text-2xl font-bold mb-3">
+						{isZh ? 'Instruction 安全约束' : 'Instruction Safety Constraints'}
+					</Heading>
+					<div className="p-4 bg-yellow-50 dark:bg-yellow-900/20 rounded-lg">
+						<h3 className="text-lg font-semibold mb-2 text-yellow-900 dark:text-yellow-300">
+							⚠️ {isZh ? '高危操作控制' : 'High-Risk Operation Control'}
+						</h3>
+						<p className="text-gray-600 dark:text-gray-300 mb-3">
+							{isZh
+								? '在 AI 指令中明确列举高危操作，通过两种策略进行控制：'
+								: 'Define high-risk operations in AI instructions and control them through two strategies:'}
+						</p>
+						<div className="space-y-2">
+							<div className="pl-3 border-l-2 border-red-400">
+								<p className="font-medium text-red-700 dark:text-red-300">
+									{isZh ? '完全禁止操作' : 'Completely Forbidden'}
+								</p>
+								<p className="text-sm text-gray-500 dark:text-gray-400">
+									{isZh
+										? '对极高风险操作明确禁止执行'
+										: 'Explicitly prohibit execution of extremely high-risk operations'}
+								</p>
+							</div>
+							<div className="pl-3 border-l-2 border-orange-400">
+								<p className="font-medium text-orange-700 dark:text-orange-300">
+									{isZh ? '需用户确认操作' : 'Requires User Confirmation'}
+								</p>
+								<p className="text-sm text-gray-500 dark:text-gray-400">
+									{isZh
+										? '对中等风险操作要求用户明确同意'
+										: 'Require explicit user consent for medium-risk operations'}
+								</p>
+							</div>
+						</div>
+					</div>
+				</section>
+			</div>
+		</div>
+	)
+}
diff --git a/packages/website/src/pages/docs/features/chrome-extension/page.tsx b/packages/website/src/pages/docs/features/chrome-extension/page.tsx
new file mode 100644
index 0000000..8ae0ea2
--- /dev/null
+++ b/packages/website/src/pages/docs/features/chrome-extension/page.tsx
@@ -0,0 +1,314 @@
+import { siChromewebstore, siGithub } from 'simple-icons'
+
+import CodeEditor from '@/components/CodeEditor'
+import { Heading } from '@/components/Heading'
+import { useLanguage } from '@/i18n/context'
+
+export default function ChromeExtension() {
+	const { isZh } = useLanguage()
+	const chromeWebStoreUrl =
+		'https://chromewebstore.google.com/detail/page-agent-ext/akldabonmimlicnjlflnapfeklbfemhj'
+	const githubReleasesUrl = 'https://github.com/alibaba/page-agent/releases'
+
+	return (
+		<div>
+			<h1 className="text-4xl font-bold mb-6">{isZh ? 'Chrome 扩展' : 'Chrome Extension'}</h1>
+
+			<p className="text-xl text-gray-600 dark:text-gray-300 mb-8 leading-relaxed">
+				{isZh
+					? '可选的 Chrome 扩展。PageAgent.js 继续负责页面内自动化；扩展 API 额外提供多页面任务、浏览器级控制，以及从浏览器外部发起任务的能力。'
+					: 'An optional Chrome extension. PageAgent.js keeps handling in-page automation, while the extension API adds multi-page tasks, browser-level control, and tasks initiated from outside the browser.'}
+			</p>
+
+			<div className="space-y-8 mt-8">
+				{/* Features */}
+				<section>
+					<Heading id="key-features" className="text-2xl font-bold mb-4">
+						{isZh ? '核心特性' : 'Key Features'}
+					</Heading>
+					<div className="grid md:grid-cols-3 gap-4">
+						<div className="p-4 bg-gray-50 dark:bg-gray-800 rounded-lg">
+							<h3 className="font-semibold mb-2">🔓 {isZh ? '多页任务' : 'Multi-Page Tasks'}</h3>
+							<p className="text-gray-600 dark:text-gray-300 text-sm">
+								{isZh
+									? '跨多个页面和标签页连续执行任务，不再受限于单页上下文。'
+									: 'Run tasks across multiple pages and tabs without being limited to a single page context.'}
+							</p>
+						</div>
+						<div className="p-4 bg-gray-50 dark:bg-gray-800 rounded-lg">
+							<h3 className="font-semibold mb-2">
+								🧭 {isZh ? '浏览器级控制' : 'Browser-Level Control'}
+							</h3>
+							<p className="text-gray-600 dark:text-gray-300 text-sm">
+								{isZh
+									? '支持跨标签导航、页面切换和更完整的浏览器自动化能力。'
+									: 'Enable richer browser automation, including cross-tab navigation and page switching.'}
+							</p>
+						</div>
+						<div className="p-4 bg-gray-50 dark:bg-gray-800 rounded-lg">
+							<h3 className="font-semibold mb-2">
+								🔌 {isZh ? '开放集成接口' : 'Open Integration API'}
+							</h3>
+							<p className="text-gray-600 dark:text-gray-300 text-sm">
+								{isZh
+									? '用户主动授权后，页面 JS、本地 Agent 或云端 Agent 可通过扩展发起多页面任务。'
+									: 'With explicit user authorization, page JS, local agents, or cloud agents can trigger multi-page tasks through the extension.'}
+							</p>
+						</div>
+					</div>
+				</section>
+
+				{/* Install */}
+				<section>
+					<Heading id="get-the-extension" className="text-2xl font-bold mb-4">
+						{isZh ? '获取扩展' : 'Get the Extension'}
+					</Heading>
+					<div className="flex flex-wrap gap-3">
+						<a
+							href={chromeWebStoreUrl}
+							target="_blank"
+							rel="noopener noreferrer"
+							className="inline-flex items-center gap-2 px-6 py-3 bg-blue-600 hover:bg-blue-700 text-white! font-medium rounded-lg transition-colors"
+						>
+							<svg className="w-5 h-5" fill="currentColor" viewBox="0 0 24 24">
+								<path d={siChromewebstore.path} />
+							</svg>
+							{isZh ? '从 Chrome 应用商店安装' : 'Install from Chrome Web Store'}
+						</a>
+						<a
+							href={githubReleasesUrl}
+							target="_blank"
+							rel="noopener noreferrer"
+							className="inline-flex items-center gap-2 px-6 py-3 bg-gray-900 hover:bg-gray-800 dark:bg-gray-700 dark:hover:bg-gray-600 text-white! font-medium rounded-lg transition-colors"
+						>
+							<svg className="w-5 h-5" fill="currentColor" viewBox="0 0 24 24">
+								<path d={siGithub.path} />
+							</svg>
+							{isZh ? 'GitHub Releases（更新版本）' : 'GitHub Releases (faster updates)'}
+						</a>
+					</div>
+				</section>
+
+				{/* Relationship with PageAgent.js */}
+				<section>
+					<Heading id="how-it-relates-to-page-agent-js" className="text-2xl font-bold mb-4">
+						{isZh ? '与 PageAgent.js 的关系' : 'How It Relates to PageAgent.js'}
+					</Heading>
+					<div className="p-5 bg-gray-50 dark:bg-gray-800 rounded-lg space-y-3 text-gray-600 dark:text-gray-300">
+						<p>
+							{isZh
+								? 'PageAgent.js 本身即可在页面内完成自动化。Chrome 扩展是可选的能力扩展。'
+								: 'PageAgent.js already works for in-page automation. The Chrome extension is optional, not a dependency.'}
+						</p>
+						<p>
+							{isZh
+								? '通过扩展，你可以执行多页面任务、控制浏览器，以及从浏览器外部（本地服务或云端服务）发起任务。'
+								: 'With the extension, you can perform multi-page tasks, browser-level control, and tasks triggered outside the browser (local or cloud services).'}
+						</p>
+					</div>
+				</section>
+
+				{/* Third-party Integration */}
+				<section>
+					<Heading id="third-party-integration" className="text-2xl font-bold mb-4">
+						{isZh ? '第三方接入' : 'Third-Party Integration'}
+					</Heading>
+					<p className="text-gray-600 dark:text-gray-300 mb-4">
+						{isZh
+							? '通过页面 JavaScript 调用 `window.PAGE_AGENT_EXT`，你的应用可以发起跨页面任务并控制浏览器行为。'
+							: 'By calling `window.PAGE_AGENT_EXT` from page JavaScript, your app can trigger multi-page tasks and control browser behavior.'}
+					</p>
+
+					<h3 className="text-xl font-semibold mb-3">
+						{isZh ? '授权与安全' : 'Authorization and Security'}
+					</h3>
+					<p className="text-gray-600 dark:text-gray-300 mb-4">
+						{isZh
+							? '扩展权限范围较广（例如页面访问、导航、多标签控制）。若被滥用，可能危害用户隐私。为此，调用能力由 Token 保护，用户必须主动将 Token 提供给其信任的应用。'
+							: 'The extension has broad permissions (such as page access, navigation, and multi-tab control). If abused, it can harm user privacy. That is why access is protected by a token, and users must actively share the token only with applications they trust.'}
+					</p>
+
+					<CodeEditor
+						code={
+							isZh
+								? `// 1) 用户在扩展侧边栏获取 auth token
+// 2) 仅在可信应用中设置该 token
+// 3) token 匹配后，扩展会暴露 window.PAGE_AGENT_EXT
+
+// ⚠️ 不要把 token 提供给不可信页面或脚本
+localStorage.setItem('PageAgentExtUserAuthToken', '<从扩展中获取的-token>')`
+								: `// 1) Get auth token from the extension side panel
+// 2) Set it only in trusted applications
+// 3) After token match, extension exposes window.PAGE_AGENT_EXT
+
+// ⚠️ Never provide the token to untrusted pages or scripts
+localStorage.setItem('PageAgentExtUserAuthToken', '<your-token-from-extension>')`
+						}
+						language="javascript"
+					/>
+				</section>
+
+				{/* API Reference */}
+				<section>
+					<Heading id="api-reference" className="text-2xl font-bold mb-4">
+						{isZh ? 'API 参考' : 'API Reference'}
+					</Heading>
+
+					{/* AI Assistant Instructions */}
+					<section className="p-4 bg-purple-50 dark:bg-purple-900/20 rounded-lg">
+						<h3 className="text-lg font-semibold text-purple-900 dark:text-purple-300 mb-2">
+							🤖 {isZh ? '给 AI 编程助手的文档' : 'Instructions for Your AI Assistant'}
+						</h3>
+						<p className="text-gray-600 dark:text-gray-300 mb-3 text-sm">
+							{isZh
+								? '如果你在使用 AI 编程助手（如 Cursor、GitHub Copilot），可以将以下文档链接提供给它，让它更好地理解和使用 Page Agent 扩展 API：'
+								: 'If you are using an AI coding assistant (like Cursor, GitHub Copilot), share these documentation links with it for better understanding of Page Agent Extension API:'}
+						</p>
+						<div className="space-y-2">
+							<a
+								href="https://github.com/alibaba/page-agent/blob/main/packages/extension/docs/extension_api.md"
+								target="_blank"
+								rel="noopener noreferrer"
+								className="block text-sm text-blue-600 hover:text-blue-700 dark:text-blue-400 dark:hover:text-blue-300 hover:underline"
+							>
+								📄 {isZh ? 'API 文档' : 'API Documentation'}
+							</a>
+						</div>
+					</section>
+
+					{/* TypeScript Declaration */}
+					<Heading id="typescript-declaration" className="text-2xl font-bold mb-4">
+						{isZh ? 'TypeScript 类型声明' : 'TypeScript Declaration'}
+					</Heading>
+					<p className="text-gray-600 dark:text-gray-300 mb-4">
+						{isZh
+							? '推荐把 `execute` 的类型声明加入你的项目，获得完整类型提示。'
+							: 'Add this `execute` declaration to your project for full type support.'}
+					</p>
+
+					<CodeEditor
+						code={`import type {
+	AgentActivity,
+	AgentStatus,
+	ExecutionResult,
+	HistoricalEvent
+} from '@page-agent/core'
+
+interface ExecuteConfig {
+	baseURL: string   // LLM API endpoint
+	model: string     // Model name
+	apiKey?: string   // LLM AK
+
+	systemInstruction?: string // Global system-level instructions
+	includeInitialTab?: boolean
+	experimentalIncludeAllTabs?: boolean // Control all unpinned tabs in the window
+	onStatusChange?: (status: AgentStatus) => void
+	onActivity?: (activity: AgentActivity) => void
+	onHistoryUpdate?: (history: HistoricalEvent[]) => void
+}
+
+type Execute = (task: string, config: ExecuteConfig) => Promise<ExecutionResult>
+
+declare global {
+	interface Window {
+		PAGE_AGENT_EXT_VERSION?: string
+		PAGE_AGENT_EXT?: {
+			version: string
+			execute: Execute
+			stop: () => void
+		}
+	}
+}`}
+						language="typescript"
+					/>
+
+					<h3 className="text-xl font-semibold mt-6 mb-3">PAGE_AGENT_EXT.execute(task, config)</h3>
+
+					<CodeEditor
+						code={
+							isZh
+								? `// 使用配置执行任务
+const result = await window.PAGE_AGENT_EXT.execute(
+	'在 GitHub 上搜索 "page-agent" 并打开第一个结果',
+	{
+		baseURL: 'https://api.openai.com/v1',
+		apiKey: 'your-api-key',
+		model: 'gpt-5.2',
+		// includeInitialTab: false, // 设为 false 排除初始标签页
+		// experimentalIncludeAllTabs: true, // 控制窗口内所有非固定标签页
+		onStatusChange: status => console.log('状态变化:', status),
+		onActivity: activity => console.log('活动:', activity),
+		onHistoryUpdate: history => console.log('历史更新:', history)
+	}
+)
+
+console.log(result) // 任务执行结果`
+								: `// Execute a task with configuration
+const result = await window.PAGE_AGENT_EXT.execute(
+	'Search for "page-agent" on GitHub and open the first result',
+	{
+		baseURL: 'https://api.openai.com/v1',
+		apiKey: 'your-api-key',
+		model: 'gpt-5.2',
+		// includeInitialTab: false, // Set to false to exclude initial tab
+		// experimentalIncludeAllTabs: true, // Control all unpinned tabs in the window
+		onStatusChange: status => console.log('Status change:', status),
+		onActivity: activity => console.log('Activity:', activity),
+		onHistoryUpdate: history => console.log('History update:', history)
+	}
+)
+
+console.log(result) // Task execution result`
+						}
+						language="javascript"
+					/>
+
+					<h3 className="text-xl font-semibold mt-6 mb-3">PAGE_AGENT_EXT.stop()</h3>
+					<p className="text-gray-600 dark:text-gray-300 mb-4">
+						{isZh ? '停止当前正在运行的任务。' : 'Stop the current running task.'}
+					</p>
+
+					<CodeEditor
+						code={
+							isZh
+								? `// 停止当前任务
+window.PAGE_AGENT_EXT.stop()`
+								: `// Stop current task execution
+window.PAGE_AGENT_EXT.stop()`
+						}
+						language="javascript"
+					/>
+				</section>
+
+				{/* Integration Guide */}
+				<section>
+					<Heading
+						id="integrate-multipageagent-into-your-extension"
+						className="text-2xl font-bold mb-4"
+					>
+						{isZh
+							? '将 MultiPageAgent 集成你自己的插件'
+							: 'Integrate MultiPageAgent into Your Extension'}
+					</Heading>
+					<p>@TODO</p>
+					<p className="text-gray-600 dark:text-gray-300 mb-4">
+						{isZh
+							? '建议先阅读扩展 API 文档，再参考 background entry implementation。'
+							: 'Start with the extension API docs, then use the background entry implementation as a reference.'}
+						<a
+							href="https://github.com/alibaba/page-agent/blob/main/packages/extension/src/entrypoints/background.ts"
+							target="_blank"
+							rel="noopener noreferrer"
+							className="inline-flex items-center gap-2 text-blue-600 hover:text-blue-700 dark:text-blue-400 dark:hover:text-blue-300"
+						>
+							<svg className="w-5 h-5" fill="currentColor" viewBox="0 0 24 24">
+								<path d={siGithub.path} />
+							</svg>
+							packages/extension/src/entrypoints/background.ts
+						</a>
+					</p>
+				</section>
+			</div>
+		</div>
+	)
+}
diff --git a/packages/website/src/pages/docs/features/custom-instructions/page.tsx b/packages/website/src/pages/docs/features/custom-instructions/page.tsx
new file mode 100644
index 0000000..2a95e4c
--- /dev/null
+++ b/packages/website/src/pages/docs/features/custom-instructions/page.tsx
@@ -0,0 +1,136 @@
+import CodeEditor from '@/components/CodeEditor'
+import { Heading } from '@/components/Heading'
+import { useLanguage } from '@/i18n/context'
+
+export default function Instructions() {
+	const { isZh } = useLanguage()
+
+	return (
+		<div>
+			<h1 className="text-4xl font-bold mb-6">{isZh ? '知识注入' : 'Instructions'}</h1>
+
+			<p className="text-xl text-gray-600 dark:text-gray-300 mb-8 leading-relaxed">
+				{isZh
+					? '通过 instructions 配置，为 AI 注入系统级指导和页面级上下文，让它更好地理解你的业务场景。'
+					: 'Use the instructions config to inject system-level directives and page-specific context, helping the AI better understand your application.'}
+			</p>
+
+			{/* System Instructions */}
+			<section className="mb-12">
+				<Heading id="system-instructions" className="text-3xl font-bold mb-6">
+					{isZh ? '系统级指导 (System Instructions)' : 'System Instructions'}
+				</Heading>
+
+				<p className="text-gray-600 dark:text-gray-300 mb-6">
+					{isZh
+						? '全局提示词，应用于所有任务。定义 AI 的角色、工作风格和行为边界。'
+						: "Global directives applied to all tasks. Define the AI's role, working style, and behavioral boundaries."}
+				</p>
+
+				<CodeEditor
+					className="mb-6"
+					code={`const agent = new PageAgent({
+  // ...other config
+  instructions: {
+    system: \`
+You are a professional e-commerce assistant.
+
+Guidelines:
+- Always confirm before submitting orders
+- Double-check prices and quantities
+- Report errors immediately instead of retrying blindly
+\`
+  }
+})`}
+				/>
+			</section>
+
+			{/* Page Instructions */}
+			<section className="mb-12">
+				<Heading id="page-instructions" className="text-3xl font-bold mb-6">
+					{isZh ? '页面级指导 (Page Instructions)' : 'Page Instructions'}
+				</Heading>
+
+				<p className="text-gray-600 dark:text-gray-300 mb-6">
+					{isZh
+						? '动态回调函数，在每个 step 执行前调用，根据当前页面 URL 返回特定提示词。适用于为不同页面提供针对性的操作引导。'
+						: 'A dynamic callback invoked before each step. Returns page-specific instructions based on the current URL. Useful for providing targeted guidance on different pages.'}
+				</p>
+
+				<CodeEditor
+					className="mb-6"
+					code={`const agent = new PageAgent({
+  // ...other config
+  instructions: {
+    system: 'You are an order management assistant.',
+
+    getPageInstructions: (url) => {
+      if (url.includes('/checkout')) {
+        return \`
+This is the checkout page.
+- Verify shipping address before proceeding
+- Check if any discounts are applied
+- Confirm the total amount with the user
+\`
+      }
+
+      if (url.includes('/products')) {
+        return \`
+This is the product listing page.
+- Use filters to narrow down search results
+- Check stock availability before adding to cart
+\`
+      }
+
+      return undefined // No special instructions for other pages
+    }
+  }
+})`}
+				/>
+			</section>
+
+			{/* How It Works */}
+			<section className="mb-12">
+				<Heading id="how-it-works" className="text-3xl font-bold mb-6">
+					{isZh ? '工作原理' : 'How It Works'}
+				</Heading>
+
+				<p className="text-gray-600 dark:text-gray-300 mb-4">
+					{isZh
+						? '在每个执行步骤之前，page-agent 会将 instructions 拼接到用户提示词中：'
+						: 'Before each execution step, page-agent prepends the instructions to the user prompt:'}
+				</p>
+
+				<CodeEditor
+					language="xml"
+					className="mb-6"
+					code={`<instructions>
+<system_instructions>
+You are a professional e-commerce assistant.
+...
+</system_instructions>
+<page_instructions>
+This is the checkout page.
+...
+</page_instructions>
+</instructions>
+
+`}
+				/>
+
+				<ul className="list-disc list-inside space-y-2 text-gray-600 dark:text-gray-400">
+					<li>
+						{isZh
+							? '如果 system 为空，则不输出 <system_instructions> 标签'
+							: 'If system is empty, the <system_instructions> tag is omitted'}
+					</li>
+					<li>
+						{isZh
+							? '如果 getPageInstructions 返回空值，则不输出 <page_instructions> 标签'
+							: 'If getPageInstructions returns empty, the <page_instructions> tag is omitted'}
+					</li>
+				</ul>
+			</section>
+		</div>
+	)
+}
diff --git a/packages/website/src/pages/docs/features/custom-tools/page.tsx b/packages/website/src/pages/docs/features/custom-tools/page.tsx
new file mode 100644
index 0000000..8f96431
--- /dev/null
+++ b/packages/website/src/pages/docs/features/custom-tools/page.tsx
@@ -0,0 +1,114 @@
+import CodeEditor from '@/components/CodeEditor'
+import { Heading } from '@/components/Heading'
+import { useLanguage } from '@/i18n/context'
+
+export default function CustomTools() {
+	const { isZh } = useLanguage()
+
+	return (
+		<div>
+			<h1 className="text-4xl font-bold mb-6">{isZh ? '自定义工具' : 'Custom Tools'}</h1>
+
+			<p className="text-xl text-gray-600 dark:text-gray-300 mb-8 leading-relaxed">
+				{isZh
+					? '通过注册自定义工具，扩展 AI Agent 的能力边界。使用 Zod 定义输入接口，让 AI 安全调用你的业务逻辑。'
+					: 'Extend AI Agent capabilities by registering custom tools. Define input schemas with Zod for safe business logic invocation.'}
+			</p>
+
+			<div className="space-y-8">
+				<section>
+					<Heading id="zod-version" className="text-2xl font-bold mb-4">
+						{isZh ? 'Zod 版本' : 'Zod Version'}
+					</Heading>
+					<p className="text-gray-600 dark:text-gray-300 mb-4">
+						{isZh
+							? 'Page Agent 使用 Zod 定义工具的输入 schema。支持 Zod 3 (>=3.25.0) 和 Zod 4，请从 zod/v4 子路径导入。不支持 Zod Mini。'
+							: 'Page Agent uses Zod for tool input schemas. Both Zod 3 (>=3.25.0) and Zod 4 are supported. Always import from the zod/v4 subpath. Zod Mini is not supported.'}
+					</p>
+					<CodeEditor
+						code={`// Zod 3 (>=3.25.0) or Zod 4
+import { z } from 'zod/v4'`}
+						language="javascript"
+					/>
+				</section>
+
+				<section>
+					<Heading id="define-tools" className="text-2xl font-bold mb-4">
+						{isZh ? '定义工具' : 'Define Tools'}
+					</Heading>
+					<p className="text-gray-600 dark:text-gray-300 mb-4">
+						{isZh
+							? '使用 tool() 辅助函数定义自定义工具，每个工具包含 description、inputSchema 和 execute 三个属性。异步工具必须 honor ctx.signal。'
+							: 'Use the tool() helper to define custom tools with description, inputSchema, and execute. Async tools must honor ctx.signal.'}
+					</p>
+
+					<CodeEditor
+						code={`import { z } from 'zod/v4'
+import { PageAgent, tool } from 'page-agent'
+
+const pageAgent = new PageAgent({
+  customTools: {
+  
+	// 
+    add_to_cart: tool({
+      description: 'Add a product to the shopping cart by its product ID.',
+      inputSchema: z.object({
+        productId: z.string(),
+        quantity: z.number().min(1).default(1),
+      }),
+      execute: async function (input, { signal }) {
+        await fetch('/api/cart', {
+          method: 'POST',
+          body: JSON.stringify(input),
+          signal, // honor cancellation
+        })
+        return \`Added \${input.quantity}x \${input.productId} to cart.\`
+      },
+    }),
+
+	// 
+    search_knowledge_base: tool({
+      description: 'Search the internal knowledge base and return relevant articles.',
+      inputSchema: z.object({
+        query: z.string(),
+        limit: z.number().max(10).default(3),
+      }),
+      execute: async function (input, { signal }) {
+        const res = await fetch(
+          \`/api/kb?q=\${encodeURIComponent(input.query)}&limit=\${input.limit}\`,
+          { signal }
+        )
+        const articles = await res.json()
+        return JSON.stringify(articles)
+      },
+    }),
+  },
+})`}
+						language="javascript"
+					/>
+				</section>
+
+				<section>
+					<Heading id="override-remove" className="text-2xl font-bold mb-4">
+						{isZh ? '覆盖与移除内置工具' : 'Override & Remove Built-in Tools'}
+					</Heading>
+					<p className="text-gray-600 dark:text-gray-300 mb-4">
+						{isZh
+							? '使用相同的名称可以覆盖内置工具的行为，设置为 null 则完全移除该工具。'
+							: 'Use the same name to override a built-in tool, or set it to null to remove it entirely.'}
+					</p>
+
+					<CodeEditor
+						code={`const pageAgent = new PageAgent({
+  customTools: {
+    scroll: null, // remove scroll tool
+    execute_javascript: null, // remove script execution
+  },
+})`}
+						language="javascript"
+					/>
+				</section>
+			</div>
+		</div>
+	)
+}
diff --git a/packages/website/src/pages/docs/features/data-masking/page.tsx b/packages/website/src/pages/docs/features/data-masking/page.tsx
new file mode 100644
index 0000000..68125bb
--- /dev/null
+++ b/packages/website/src/pages/docs/features/data-masking/page.tsx
@@ -0,0 +1,74 @@
+import CodeEditor from '@/components/CodeEditor'
+import { Heading } from '@/components/Heading'
+import { useLanguage } from '@/i18n/context'
+
+export default function DataMasking() {
+	const { isZh } = useLanguage()
+
+	return (
+		<div>
+			<h1 className="text-4xl font-bold mb-6">{isZh ? '数据脱敏' : 'Data Masking'}</h1>
+
+			<p className="text-xl text-gray-600 dark:text-gray-300 mb-8 leading-relaxed">
+				{isZh
+					? '使用 transformPageContent 钩子在页面内容发送给 LLM 之前进行处理，可用于检查清洗效果、修改页面信息、隐藏敏感数据等。'
+					: 'Use the transformPageContent hook to process page content before sending to LLM. Useful for inspecting extraction results, modifying page info, and masking sensitive data.'}
+			</p>
+
+			<section className="mb-12">
+				<Heading id="api-definition" className="text-3xl font-bold mb-6">
+					{isZh ? '接口定义' : 'API Definition'}
+				</Heading>
+
+				<CodeEditor
+					className="mb-6"
+					code={`interface PageAgentConfig {
+  /**
+   * Transform page content before sending to LLM.
+   * Called after DOM extraction and simplification.
+   */
+  transformPageContent?: (content: string) => Promise<string> | string
+}`}
+				/>
+			</section>
+
+			<section className="mb-12">
+				<Heading id="common-masking-patterns" className="text-3xl font-bold mb-6">
+					{isZh ? '常用脱敏规则' : 'Common Masking Patterns'}
+				</Heading>
+
+				<p className="text-gray-600 dark:text-gray-300 mb-6">
+					{isZh
+						? '以下示例展示了如何脱敏常见的敏感信息：'
+						: 'The following example shows how to mask common sensitive data:'}
+				</p>
+
+				<CodeEditor
+					code={`const agent = new PageAgent({
+  transformPageContent: async (content) => {
+    // China phone number (11 digits starting with 1)
+    content = content.replace(/\\b(1[3-9]\\d)(\\d{4})(\\d{4})\\b/g, '$1****$3')
+
+    // Email address
+    content = content.replace(
+      /\\b([a-zA-Z0-9._%+-])[^@]*(@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,})\\b/g,
+      '$1***$2'
+    )
+
+    // China ID card number (18 digits)
+    content = content.replace(
+      /\\b(\\d{6})(19|20\\d{2})(0[1-9]|1[0-2])(0[1-9]|[12]\\d|3[01])(\\d{3}[\\dXx])\\b/g,
+      '$1********$5'
+    )
+
+    // Bank card number (16-19 digits)
+    content = content.replace(/\\b(\\d{4})\\d{8,11}(\\d{4})\\b/g, '$1********$2')
+
+    return content
+  }
+})`}
+				/>
+			</section>
+		</div>
+	)
+}
diff --git a/packages/website/src/pages/docs/features/mcp-server/page.tsx b/packages/website/src/pages/docs/features/mcp-server/page.tsx
new file mode 100644
index 0000000..b31454f
--- /dev/null
+++ b/packages/website/src/pages/docs/features/mcp-server/page.tsx
@@ -0,0 +1,70 @@
+import BetaNotice from '@/components/BetaNotice'
+import CodeEditor from '@/components/CodeEditor'
+import { Heading } from '@/components/Heading'
+
+export default function McpServerPage() {
+	return (
+		<div>
+			<h1 className="text-4xl font-bold mb-6">MCP Server (Beta)</h1>
+			<BetaNotice />
+			<p className="text-xl text-gray-600 dark:text-gray-300 mb-8 leading-relaxed">
+				Use the MCP server to let your local agent send natural-language browser tasks to Page Agent
+				Ext.
+			</p>
+
+			<section className="mb-10">
+				<Heading id="quick-start" className="text-2xl font-bold mb-4">
+					How to use
+				</Heading>
+				<div className="space-y-4">
+					<div className="p-4 bg-blue-50 dark:bg-blue-950/20 rounded-lg border border-blue-200 dark:border-blue-800">
+						<p className="text-sm text-blue-900 dark:text-blue-200 leading-7">
+							1. Install Page Agent Ext in Chrome.
+							<br />
+							2. Add the MCP server to your local agent client.
+							<br />
+							3. Start the client and approve the Hub connection in the browser when prompted.
+							<br />
+							4. Ask your agent to do something in the browser. The client will call execute_task
+							for you.
+						</p>
+					</div>
+
+					<CodeEditor
+						code={`{
+  "mcpServers": {
+    "page-agent": {
+      "command": "npx",
+      "args": ["-y", "@page-agent/mcp"],
+      "env": {
+        "LLM_BASE_URL": "https://api.openai.com/v1",
+        "LLM_API_KEY": "sk-xxx",
+        "LLM_MODEL_NAME": "gpt-5.2"
+      }
+    }
+  }
+}`}
+						language="json"
+					/>
+				</div>
+			</section>
+
+			<section className="mb-10">
+				<Heading id="the-hub" className="text-2xl font-bold mb-4">
+					The Hub
+				</Heading>
+
+				<p className="text-gray-700 dark:text-gray-300 leading-relaxed">
+					The Hub is the control center for communication between Page Agent Ext and external
+					callers.
+				</p>
+				<p className="text-gray-700 dark:text-gray-300 leading-relaxed">
+					When the MCP server starts, it opens a local launcher page. The launcher asks the
+					extension to open the Hub tab, and the Hub receives tasks from your local agent. MCP uses
+					this path, but the Hub itself is the extension's general external communication entry
+					point.
+				</p>
+			</section>
+		</div>
+	)
+}
diff --git a/packages/website/src/pages/docs/features/models/page.tsx b/packages/website/src/pages/docs/features/models/page.tsx
new file mode 100644
index 0000000..b47dbca
--- /dev/null
+++ b/packages/website/src/pages/docs/features/models/page.tsx
@@ -0,0 +1,474 @@
+import { Fragment } from 'react'
+import { Link } from 'wouter'
+
+import CodeEditor from '@/components/CodeEditor'
+import { Heading } from '@/components/Heading'
+import { useLanguage } from '@/i18n/context'
+
+const BASELINE = new Set([
+	'gpt-5.4-mini',
+	'gpt-5.4-nano',
+	'claude-haiku-4-5',
+	'gemini-3.5-flash',
+	'deepseek-v4-flash',
+	'qwen3.5-plus',
+	'qwen3.5-flash',
+])
+
+// Models grouped by brand, newest first
+const MODEL_GROUPS: Record<string, string[]> = {
+	Qwen: [
+		'qwen3.7-max',
+		'qwen3.7-plus',
+		'qwen3.6-max',
+		'qwen3.6-plus',
+		'qwen3.6-flash',
+		'qwen3.5-plus',
+		'qwen3.5-flash',
+		'qwen3-max',
+		// 'qwen3-coder-next', // low success rate
+	],
+	OpenAI: [
+		'gpt-5.6-sol',
+		'gpt-5.6-terra',
+		'gpt-5.6-luna',
+		'gpt-5.5',
+		'gpt-5.4',
+		'gpt-5.4-mini',
+		'gpt-5.4-nano',
+		'gpt-5.2',
+		'gpt-5.1',
+		'gpt-5',
+		'gpt-5-mini',
+		'gpt-4.1',
+		'gpt-4.1-mini',
+	],
+	DeepSeek: ['deepseek-v4-pro', 'deepseek-v4-flash', 'deepseek-3.2'],
+	Google: [
+		'gemini-3.5-flash',
+		'gemini-3.1-pro',
+		'gemini-3.1-flash-lite',
+		'gemini-2.5-pro',
+		'gemini-2.5-flash',
+	],
+	Anthropic: [
+		'claude-sonnet-5',
+		'claude-fable-5',
+		'claude-opus-4-8',
+		'claude-opus-4-7',
+		'claude-opus-4-6',
+		'claude-opus-4-5',
+		'claude-sonnet-4-5',
+		'claude-haiku-4-5',
+	],
+	MiniMax: [
+		// 'MiniMax-M3', low success rate
+		'MiniMax-M2.7',
+		'MiniMax-M2.5',
+	],
+	xAI: ['grok-4.5', 'grok-4.3', 'grok-build-0.1'],
+	Tencent: ['hy3'],
+	MoonshotAI: ['kimi-k2.7-code', 'kimi-k2.6', 'kimi-k2.5'],
+	'Z.AI': ['glm-5.2', 'glm-5.1', 'glm-5', 'glm-4.7'],
+}
+
+const ModelBadge = ({ model, baseline }: { model: string; baseline?: boolean }) => (
+	<div
+		className={`px-3 py-1.5 rounded-md text-xs font-medium font-mono transition-colors ${
+			baseline
+				? 'bg-emerald-500 text-white shadow-sm'
+				: 'bg-white/80 dark:bg-gray-800/80 text-gray-800 dark:text-gray-200 border border-gray-300 dark:border-gray-600'
+		}`}
+	>
+		{model}
+		{baseline && <span className="ml-1">⭐</span>}
+	</div>
+)
+
+export default function Models() {
+	const { isZh } = useLanguage()
+
+	return (
+		<div className="max-w-4xl">
+			<h1 className="text-4xl font-bold mb-4">{isZh ? '模型' : 'Models'}</h1>
+			<p className="text-lg text-gray-600 dark:text-gray-400 mb-8">
+				{isZh
+					? '当前支持符合 OpenAI 接口规范且支持 tool call 的模型,包括公有云服务和私有部署方案。'
+					: 'Supports models that comply with OpenAI API specification and support tool calls, including public cloud services and private deployments.'}
+			</p>
+
+			<section className="mb-10">
+				<Heading id="tested-models" className="text-2xl font-semibold mb-3">
+					{isZh ? '模型列表' : 'Model List'}
+				</Heading>
+				<div className="bg-linear-to-br from-emerald-50 to-cyan-50 dark:from-emerald-950/30 dark:to-cyan-950/30 rounded-xl p-6 border border-emerald-200/50 dark:border-emerald-800/50">
+					<div className="grid grid-cols-[5rem_1fr] gap-x-3 gap-y-3 items-start">
+						{Object.entries(MODEL_GROUPS).map(([brand, models]) => (
+							<Fragment key={brand}>
+								<span className="text-xs font-semibold text-gray-500 dark:text-gray-400 pt-2">
+									{brand}
+								</span>
+								<div className="flex flex-wrap gap-2">
+									{models.map((model) => (
+										<ModelBadge key={model} model={model} baseline={BASELINE.has(model)} />
+									))}
+								</div>
+							</Fragment>
+						))}
+					</div>
+				</div>
+			</section>
+
+			<section className="mb-10">
+				<Heading id="tips" level={3}>
+					Tips
+				</Heading>
+				<div className="p-4 bg-blue-50 dark:bg-blue-950/20 rounded-lg border border-blue-200 dark:border-blue-800">
+					<ul className="text-sm text-gray-700 dark:text-gray-300 space-y-2 list-disc pl-5">
+						<li>
+							{isZh
+								? '⭐ 推荐使用 ToolCall 能力强的轻量级模型'
+								: '⭐ Recommended: Fast, lightweight models with strong ToolCall capabilities'}
+						</li>
+						<li>
+							{isZh
+								? 'ToolCall 能力较弱的模型可能返回错误的格式，常见错误能够自动恢复'
+								: 'Models with weaker ToolCall capabilities may return incorrect formats. Common errors usually auto-recover'}
+						</li>
+						<li>
+							{isZh
+								? '小模型或者无法适应复杂 Tool 定义的模型，通常效果不佳'
+								: 'Small models or those unable to handle complex tool definitions typically perform poorly'}
+						</li>
+					</ul>
+				</div>
+			</section>
+
+			<section className="mb-10">
+				<Heading id="configuration">{isZh ? '配置方式' : 'Configuration'}</Heading>
+				<CodeEditor
+					code={`// OpenAI-compatible services (e.g., Alibaba Bailian)
+const pageAgent = new PageAgent({
+  baseURL: 'https://dashscope.aliyuncs.com/compatible-mode/v1',
+  apiKey: 'your-api-key',
+  model: 'qwen3.5-plus'
+});
+`}
+				/>
+			</section>
+
+			<section className="mb-10">
+				<Heading id="free-testing-api">{isZh ? '免费测试接口' : 'Free Testing API'}</Heading>
+				<p className="text-sm text-gray-600 dark:text-gray-400 mb-4">
+					{isZh
+						? '以下免费测试接口仅供 PageAgent.js 和 PageAgent Extension 的技术评估和测试使用。'
+						: 'The following free testing endpoint is provided for testing and technical evaluation.'}
+				</p>
+				<div className="my-4 p-4 bg-amber-50 dark:bg-amber-950/20 rounded-lg border border-amber-200 dark:border-amber-800">
+					<p className="text-xs text-gray-600 dark:text-gray-400">
+						{isZh
+							? '⚠️ 仅供技术评估和研发用途，禁止用于生产环境。数据通过中国大陆服务器处理。请勿输入任何个人身份信息或敏感数据。使用即表示您同意'
+							: '⚠️ Strictly for technical evaluation and R&D only. Data is processed via servers in Mainland China. Do not input any PII or sensitive data. By using this API you agree to the'}{' '}
+						<a
+							href="https://github.com/alibaba/page-agent/blob/main/docs/terms-and-privacy.md#2-testing-api-and-demo-disclaimer--terms-of-use"
+							target="_blank"
+							rel="noopener noreferrer"
+							className="text-blue-500 hover:underline"
+						>
+							{isZh ? '使用条款' : 'Terms of Use'}
+						</a>
+					</p>
+				</div>
+				<div className="bg-gray-50 dark:bg-gray-900/30 rounded-lg p-5 border border-gray-200 dark:border-gray-800">
+					<h3 className="font-semibold text-gray-900 dark:text-gray-100 mb-2">
+						Qwen (Alibaba Cloud China)
+					</h3>
+					<p className="text-xs text-gray-500 dark:text-gray-400 mb-3">
+						{isZh
+							? '通过阿里云函数计算（中国大陆）转发至百炼 Qwen 模型'
+							: 'Proxied via Alibaba Cloud FC (Mainland China) to BaiLian Qwen models'}
+						{' · '}
+						<a
+							href="https://github.com/alibaba/page-agent/blob/main/docs/terms-and-privacy.md#2-testing-api-and-demo-disclaimer--terms-of-use"
+							target="_blank"
+							rel="noopener noreferrer"
+							className="text-blue-500 hover:underline"
+						>
+							{isZh ? '使用条款' : 'Terms of Use'}
+						</a>
+					</p>
+					<CodeEditor
+						code={`# qwen3.5-plus / qwen3.5-flash
+LLM_BASE_URL="https://page-ag-testing-ohftxirgbn.cn-shanghai.fcapp.run"
+LLM_MODEL_NAME="qwen3.5-plus"`}
+					/>
+				</div>
+			</section>
+
+			<section className="mb-10">
+				<Heading id="production-authentication" className="text-2xl font-semibold mb-4">
+					{isZh ? '🔐 生产环境鉴权' : '🔐 Production Authentication'}
+				</Heading>
+				<p className="text-sm text-gray-600 dark:text-gray-400 mb-3">
+					{isZh
+						? '如果你只是将它用作个人助手，可以直接连接你的 LLM 服务。'
+						: 'If you only use it as a personal assistant, you can connect to your LLM service directly.'}
+				</p>
+				<p className="text-sm text-gray-600 dark:text-gray-400 mb-3">
+					{isZh ? (
+						<>
+							如果你计划将它集成到你的 Web 应用中，建议搭建一个后端代理来转发 LLM 请求，并使用{' '}
+							<code>customFetch</code> 携带 Cookie 或其他鉴权信息：
+						</>
+					) : (
+						<>
+							If you plan to integrate it into your web app, it's better to have a backend proxy for
+							the LLM and use <code>customFetch</code> to authenticate the request with cookies or
+							other methods:
+						</>
+					)}
+				</p>
+				<CodeEditor
+					code={`const agent = new PageAgent({
+  baseURL: '/api/llm-proxy',
+  model: 'gpt-5.1',
+  customFetch: (url, init) =>
+    fetch(url, { ...init, credentials: 'include' }),
+});`}
+				/>
+				<div className="mt-4 bg-yellow-50 dark:bg-yellow-950/20 border-l-4 border-yellow-500 p-4 rounded-r-lg">
+					<p className="text-sm font-semibold text-yellow-900 dark:text-yellow-200">
+						{isZh
+							? '⚠️ 永远不要把真实的 LLM API Key 提交到前端代码中'
+							: '⚠️ NEVER commit real LLM API keys to your frontend code'}
+					</p>
+				</div>
+			</section>
+
+			<section className="mb-10">
+				<Heading id="prompt-caching">{isZh ? '主动缓存' : 'Prompt Caching'}</Heading>
+				<p className="text-sm text-gray-600 dark:text-gray-400 mb-4">
+					{isZh ? (
+						<>
+							一些 LLM 能从主动缓存中受益很多。由于各个供应商的主动缓存接口不同，推荐使用{' '}
+							<Link
+								href="/advanced/page-agent-core#configuration"
+								className="text-blue-600 dark:text-blue-400 hover:underline"
+							>
+								transformRequestBody
+							</Link>{' '}
+							为你的模型供应商配置缓存提示。
+						</>
+					) : (
+						<>
+							Some LLMs benefit significantly from prompt caching. Because each provider exposes
+							caching differently, use{' '}
+							<Link
+								href="/advanced/page-agent-core#configuration"
+								className="text-blue-600 dark:text-blue-400 hover:underline"
+							>
+								transformRequestBody
+							</Link>{' '}
+							to add provider-specific cache hints.
+						</>
+					)}
+				</p>
+
+				<div className="space-y-6">
+					<section>
+						<Heading id="prompt-caching-claude" level={3}>
+							Claude
+						</Heading>
+						<p className="text-sm text-gray-600 dark:text-gray-400 mb-4">
+							{isZh
+								? 'Claude 支持全局 Automatic prompt caching。使用兼容 Claude 的代理时，只需要在请求体顶层添加 cache_control。'
+								: 'Claude supports global Automatic prompt caching. When using a Claude-compatible proxy, add cache_control at the top level of the request body.'}
+						</p>
+						<CodeEditor
+							language="typescript"
+							code={`const pageAgent = new PageAgent({
+  baseURL: 'https://your-claude-proxy.example/v1',
+  apiKey: 'your-api-key',
+  model: 'claude-sonnet-5',
+  transformRequestBody: (requestBody) => ({
+    ...requestBody,
+    cache_control: { type: 'ephemeral' },
+  }),
+});`}
+						/>
+					</section>
+					<section>
+						<Heading id="prompt-caching-qwen" level={3}>
+							{isZh ? '阿里云百炼 Qwen' : 'Alibaba Cloud Bailian Qwen'}
+						</Heading>
+						<CodeEditor
+							language="typescript"
+							code={`const pageAgent = new PageAgent({
+  baseURL: 'https://dashscope.aliyuncs.com/compatible-mode/v1',
+  apiKey: 'your-api-key',
+  model: 'qwen3.5-plus',
+  transformRequestBody: (requestBody) => {
+    const [systemMessage, ...restMessages] = requestBody.messages
+
+    if (systemMessage.role !== 'system' || typeof systemMessage.content !== 'string') {
+      return requestBody
+    }
+
+    return {
+      ...requestBody,
+      messages: [
+        {
+          ...systemMessage,
+          content: [
+            {
+              type: 'text',
+              text: systemMessage.content,
+              cache_control: { type: 'ephemeral' },
+            },
+          ],
+        },
+        ...restMessages,
+      ],
+    }
+  },
+});`}
+						/>
+					</section>
+				</div>
+			</section>
+
+			<section className="mb-10">
+				<Heading id="local-runtimes">{isZh ? '本地 LLMs' : 'Local LLMs'}</Heading>
+				<p className="text-sm text-gray-600 dark:text-gray-400 mb-6">
+					{isZh
+						? '通过 Ollama、LM Studio 等本地 OpenAI-compatible 运行时接入 PageAgent，实现离线或局域网部署。'
+						: 'Use local OpenAI-compatible runtimes such as Ollama and LM Studio with PageAgent for offline or LAN deployments.'}
+				</p>
+
+				<div className="space-y-10">
+					<section>
+						<Heading id="requirements" level={3}>
+							Requirements
+						</Heading>
+						<div className="mt-4 p-5 bg-amber-50 dark:bg-amber-950/20 rounded-xl border border-amber-200 dark:border-amber-800">
+							<ul className="text-sm text-gray-700 dark:text-gray-300 space-y-2 list-disc pl-5">
+								<li>
+									{isZh
+										? '务必打开 CORS，否则浏览器无法直接请求本地 LLM 服务。'
+										: 'Enable CORS, otherwise the browser cannot call your local LLM endpoint directly.'}
+								</li>
+								<li>
+									{isZh
+										? '将 context length 或 content length 至少设置为 8000。普通页面常常需要 15k token 左右，默认 4k 很容易被截断。'
+										: 'Set context length or content length to at least 8000. A typical page often needs around 15k tokens, so the default 4k usually truncates prompts.'}
+								</li>
+								<li>
+									{isZh ? '需要支持 tool_call 的模型。' : 'Use a model with tool_call support.'}
+								</li>
+								<li>
+									{isZh
+										? '小于 10B 参数的模型通常效果不佳。'
+										: 'Models smaller than 10B are usually not strong enough.'}
+								</li>
+							</ul>
+						</div>
+					</section>
+
+					<section>
+						<Heading id="local-configuration" level={3}>
+							{isZh ? '基础配置' : 'Basic Configuration'}
+						</Heading>
+						<CodeEditor
+							code={`// Local OpenAI-compatible runtime - no apiKey needed
+const pageAgent = new PageAgent({
+  baseURL: 'http://localhost:11434/v1',
+  model: 'qwen3:14b'
+});
+
+// Or connect to LM Studio
+const lmStudioAgent = new PageAgent({
+  baseURL: 'http://127.0.0.1:1234/v1',
+  model: 'qwen/qwen3.5-27b'
+});
+`}
+						/>
+					</section>
+
+					<section>
+						<Heading id="ollama" level={3}>
+							Ollama
+						</Heading>
+						<p className="text-sm text-gray-600 dark:text-gray-400 mb-4">
+							{isZh
+								? '已在 Ollama 0.15 + qwen3:14b (RTX3090 24GB) 上测试通过。'
+								: 'Tested on Ollama 0.15 with qwen3:14b (RTX3090 24GB).'}
+						</p>
+						<CodeEditor
+							code={`LLM_BASE_URL="http://localhost:11434/v1"
+LLM_MODEL_NAME="qwen3:14b"`}
+						/>
+						<div className="mt-4 p-4 bg-amber-50 dark:bg-amber-950/20 rounded-lg border border-amber-200 dark:border-amber-800">
+							<h3 className="font-semibold text-amber-900 dark:text-amber-200 mb-2">
+								{isZh ? '⚠️ 注意事项' : '⚠️ Important Notes'}
+							</h3>
+							<p className="text-sm text-gray-700 dark:text-gray-300">
+								{isZh
+									? '如果浏览器侧请求失败，优先检查 Ollama 是否已按上面的要求开启 CORS。'
+									: 'If browser-side requests fail, check whether Ollama has CORS enabled as required above.'}
+							</p>
+						</div>
+
+						<div className="mt-4">
+							<h3 className="font-semibold text-gray-900 dark:text-gray-100 mb-3">
+								{isZh ? '建议启动参数' : 'Recommended Startup'}
+							</h3>
+							<p className="text-sm text-gray-600 dark:text-gray-400 mb-3">
+								{isZh
+									? '启动 Ollama 时建议同时放大上下文窗口并开启跨域访问。'
+									: 'When starting Ollama, increase the context window and enable cross-origin access.'}
+							</p>
+
+							<div className="space-y-2">
+								<p className="text-xs font-medium text-gray-500 dark:text-gray-400">
+									macOS / Linux
+								</p>
+								<CodeEditor
+									code={`OLLAMA_CONTEXT_LENGTH=64000 OLLAMA_HOST=0.0.0.0:11434 OLLAMA_ORIGINS="*" ollama serve`}
+								/>
+
+								<p className="text-xs font-medium text-gray-500 dark:text-gray-400 pt-2">
+									Windows (PowerShell)
+								</p>
+								<CodeEditor
+									code={`$env:OLLAMA_CONTEXT_LENGTH=64000; $env:OLLAMA_HOST="0.0.0.0:11434"; $env:OLLAMA_ORIGINS="*"; ollama serve`}
+								/>
+							</div>
+						</div>
+					</section>
+
+					<section>
+						<Heading id="lm-studio" level={3}>
+							LM Studio
+						</Heading>
+						<CodeEditor
+							code={`LLM_BASE_URL="http://127.0.0.1:1234/v1"
+LLM_MODEL_NAME="qwen/qwen3.5-27b"`}
+						/>
+						<div className="mt-4 p-4 bg-amber-50 dark:bg-amber-950/20 rounded-lg border border-amber-200 dark:border-amber-800">
+							<h3 className="font-semibold text-amber-900 dark:text-amber-200 mb-2">
+								{isZh ? '⚠️ 注意事项' : '⚠️ Important Notes'}
+							</h3>
+							<ul className="text-sm text-gray-700 dark:text-gray-300 space-y-2 list-disc pl-5">
+								<li>
+									{isZh
+										? 'Agent 必须启用 disableNamedToolChoice，否则 tool_choice 参数会报错。'
+										: 'Enable disableNamedToolChoice in the agent config, otherwise the tool_choice parameter may fail.'}
+								</li>
+							</ul>
+						</div>
+					</section>
+				</div>
+			</section>
+		</div>
+	)
+}
diff --git a/packages/website/src/pages/docs/features/third-party-agent/page.tsx b/packages/website/src/pages/docs/features/third-party-agent/page.tsx
new file mode 100644
index 0000000..8ced7dc
--- /dev/null
+++ b/packages/website/src/pages/docs/features/third-party-agent/page.tsx
@@ -0,0 +1,99 @@
+import CodeEditor from '@/components/CodeEditor'
+import { Heading } from '@/components/Heading'
+import { useLanguage } from '@/i18n/context'
+
+export default function ThirdPartyAgentPage() {
+	const { isZh } = useLanguage()
+
+	return (
+		<div>
+			<h1 className="text-4xl font-bold mb-6">
+				{isZh ? '接入第三方 Agent' : 'Third-party Agent Integration'}
+			</h1>
+			<p className="mb-6 leading-relaxed text-gray-600 dark:text-gray-300">
+				{isZh
+					? '将 pageAgent 作为工具接入你的答疑助手或 Agent 系统，成为你 Agent 的眼和手。'
+					: 'Integrate pageAgent as a tool in your support assistant or Agent system, becoming the eyes and hands of your Agent.'}
+			</p>
+
+			<Heading id="integration-method" className="text-2xl font-bold mb-4">
+				{isZh ? '集成方式' : 'Integration Method'}
+			</Heading>
+
+			<div className="space-y-4 mb-6">
+				<div className="p-4 bg-green-50 dark:bg-green-900/20 rounded-lg">
+					<h3 className="text-lg font-semibold mb-2 text-green-900 dark:text-green-300">
+						1. Function Calling
+					</h3>
+					<CodeEditor
+						code={`// ${isZh ? '定义工具' : 'Define tool'}
+const pageAgentTool = {
+  name: "page_agent",
+  description: "${isZh ? '执行网页操作' : 'Execute web page operations'}",
+  parameters: {
+    type: "object",
+    properties: {
+      instruction: { type: "string", description: "${isZh ? '操作指令' : 'Operation instruction'}" }
+    },
+    required: ["instruction"]
+  },
+  execute: async (params) => {
+    const result = await pageAgent.execute(params.instruction)
+    return { success: result.success, message: result.data }
+  }
+}
+
+// ${isZh ? '注册到你的 agent 中' : 'Register to your agent'}`}
+						language="javascript"
+					/>
+				</div>
+			</div>
+
+			<Heading id="use-cases" className="text-2xl font-bold mb-4">
+				{isZh ? '应用场景' : 'Use Cases'}
+			</Heading>
+			<div className="grid md:grid-cols-2 gap-4 mb-6">
+				<div className="bg-linear-to-br from-blue-50 to-purple-50 dark:from-gray-800 dark:to-gray-700 p-4 rounded-lg">
+					<h4 className="font-semibold mb-2 text-gray-900 dark:text-white">
+						{isZh ? '🤖 智能客服系统' : '🤖 Smart Customer Service'}
+					</h4>
+					<p className="text-sm text-gray-600 dark:text-gray-300">
+						{isZh
+							? '客服机器人帮用户直接操作系统，如"帮我提交工单"'
+							: 'Support bots directly operate systems for users, e.g., "Help me submit a ticket"'}
+					</p>
+				</div>
+				<div className="bg-linear-to-br from-green-50 to-blue-50 dark:from-gray-800 dark:to-gray-700 p-4 rounded-lg">
+					<h4 className="font-semibold mb-2 text-gray-900 dark:text-white">
+						{isZh ? '📋 业务流程助手' : '📋 Business Process Assistant'}
+					</h4>
+					<p className="text-sm text-gray-600 dark:text-gray-300">
+						{isZh
+							? '引导新员工完成复杂流程，如"完成客户入职"'
+							: 'Guide new employees through complex processes, e.g., "Complete customer onboarding"'}
+					</p>
+				</div>
+				<div className="bg-linear-to-br from-purple-50 to-pink-50 dark:from-gray-800 dark:to-gray-700 p-4 rounded-lg">
+					<h4 className="font-semibold mb-2 text-gray-900 dark:text-white">
+						{isZh ? '🎯 个人效率助手' : '🎯 Personal Productivity Assistant'}
+					</h4>
+					<p className="text-sm text-gray-600 dark:text-gray-300">
+						{isZh
+							? '跨网站帮你完成任务，如"预订会议室"'
+							: 'Complete tasks across websites, e.g., "Book a meeting room"'}
+					</p>
+				</div>
+				<div className="bg-linear-to-br from-orange-50 to-red-50 dark:from-gray-800 dark:to-gray-700 p-4 rounded-lg">
+					<h4 className="font-semibold mb-2 text-gray-900 dark:text-white">
+						{isZh ? '🔧 运维自动化' : '🔧 DevOps Automation'}
+					</h4>
+					<p className="text-sm text-gray-600 dark:text-gray-300">
+						{isZh
+							? '通过自然语言操作管理后台，如"重启服务器"'
+							: 'Operate admin panels via natural language, e.g., "Restart server"'}
+					</p>
+				</div>
+			</div>
+		</div>
+	)
+}
diff --git a/packages/website/src/pages/docs/index.tsx b/packages/website/src/pages/docs/index.tsx
new file mode 100644
index 0000000..a614ca1
--- /dev/null
+++ b/packages/website/src/pages/docs/index.tsx
@@ -0,0 +1,130 @@
+import { Suspense } from 'react'
+import { Route, Switch } from 'wouter'
+
+import DocsLayout from './Layout'
+import CustomUIDocs from './advanced/custom-ui/page'
+import PageAgentCoreDocs from './advanced/page-agent-core/page'
+// Advanced
+import PageAgentDocs from './advanced/page-agent/page'
+import PageControllerDocs from './advanced/page-controller/page'
+import SecurityPermissions from './advanced/security-permissions/page'
+// Features
+import ChromeExtension from './features/chrome-extension/page'
+import Instructions from './features/custom-instructions/page'
+import CustomTools from './features/custom-tools/page'
+import DataMasking from './features/data-masking/page'
+import McpServerPage from './features/mcp-server/page'
+import Models from './features/models/page'
+import ThirdPartyAgent from './features/third-party-agent/page'
+import Limitations from './introduction/limitations/page'
+// Introduction
+import Overview from './introduction/overview/page'
+import QuickStart from './introduction/quick-start/page'
+import Troubleshooting from './introduction/troubleshooting/page'
+
+function DocsPage({ children }: { children: React.ReactNode }) {
+	return (
+		<DocsLayout>
+			<Suspense>{children}</Suspense>
+		</DocsLayout>
+	)
+}
+
+export default function DocsRouter() {
+	return (
+		<Switch>
+			{/* Introduction */}
+			<Route path="/introduction/overview">
+				<DocsPage>
+					<Overview />
+				</DocsPage>
+			</Route>
+			<Route path="/introduction/quick-start">
+				<DocsPage>
+					<QuickStart />
+				</DocsPage>
+			</Route>
+			<Route path="/introduction/limitations">
+				<DocsPage>
+					<Limitations />
+				</DocsPage>
+			</Route>
+			<Route path="/introduction/troubleshooting">
+				<DocsPage>
+					<Troubleshooting />
+				</DocsPage>
+			</Route>
+
+			{/* Features */}
+			<Route path="/features/custom-tools">
+				<DocsPage>
+					<CustomTools />
+				</DocsPage>
+			</Route>
+			<Route path="/features/data-masking">
+				<DocsPage>
+					<DataMasking />
+				</DocsPage>
+			</Route>
+			<Route path="/features/custom-instructions">
+				<DocsPage>
+					<Instructions />
+				</DocsPage>
+			</Route>
+			<Route path="/features/models">
+				<DocsPage>
+					<Models />
+				</DocsPage>
+			</Route>
+			<Route path="/features/chrome-extension">
+				<DocsPage>
+					<ChromeExtension />
+				</DocsPage>
+			</Route>
+			<Route path="/features/mcp-server">
+				<DocsPage>
+					<McpServerPage />
+				</DocsPage>
+			</Route>
+			<Route path="/features/third-party-agent">
+				<DocsPage>
+					<ThirdPartyAgent />
+				</DocsPage>
+			</Route>
+
+			{/* Advanced */}
+			<Route path="/advanced/page-agent">
+				<DocsPage>
+					<PageAgentDocs />
+				</DocsPage>
+			</Route>
+			<Route path="/advanced/page-agent-core">
+				<DocsPage>
+					<PageAgentCoreDocs />
+				</DocsPage>
+			</Route>
+			<Route path="/advanced/page-controller">
+				<DocsPage>
+					<PageControllerDocs />
+				</DocsPage>
+			</Route>
+			<Route path="/advanced/custom-ui">
+				<DocsPage>
+					<CustomUIDocs />
+				</DocsPage>
+			</Route>
+			<Route path="/advanced/security-permissions">
+				<DocsPage>
+					<SecurityPermissions />
+				</DocsPage>
+			</Route>
+
+			{/* Default redirect or 404 */}
+			<Route path="/docs">
+				<DocsPage>
+					<Overview />
+				</DocsPage>
+			</Route>
+		</Switch>
+	)
+}
diff --git a/packages/website/src/pages/docs/introduction/limitations/page.tsx b/packages/website/src/pages/docs/introduction/limitations/page.tsx
new file mode 100644
index 0000000..6120a43
--- /dev/null
+++ b/packages/website/src/pages/docs/introduction/limitations/page.tsx
@@ -0,0 +1,158 @@
+import { Link } from 'wouter'
+
+import { Heading } from '@/components/Heading'
+import { useLanguage } from '@/i18n/context'
+
+export default function LimitationsPage() {
+	const { isZh } = useLanguage()
+
+	return (
+		<div className="max-w-4xl mx-auto">
+			<div className="mb-8">
+				<h1 className="text-4xl font-bold mb-4 text-gray-900 dark:text-white">
+					{isZh ? '使用限制' : 'Limitations'}
+				</h1>
+				<p className="text-xl text-gray-600 dark:text-gray-300">
+					{isZh
+						? 'Page Agent 基于 DOM 理解网页并执行操作。这决定了它的能力边界。'
+						: 'Page Agent understands web pages via DOM and performs actions accordingly. This defines its capability boundary.'}
+				</p>
+			</div>
+
+			<div className="prose prose-lg dark:prose-invert max-w-none">
+				{/* PageAgent.js vs PageAgentExt */}
+				<Heading id="pageagent-js-vs-pageagentext" className="text-2xl font-bold mb-3">
+					{isZh ? 'PageAgent.js vs PageAgentExt' : 'PageAgent.js vs PageAgentExt'}
+				</Heading>
+				<p className="text-gray-600 dark:text-gray-300 mb-4">
+					{isZh
+						? 'PageAgent.js 是核心库，运行在页面内。PageAgentExt 是可选的浏览器扩展，提供额外的浏览器级控制能力。'
+						: 'PageAgent.js is the core library running inside a page. PageAgentExt is an optional browser extension that adds browser-level control.'}
+				</p>
+				<div className="overflow-x-auto mb-6">
+					<table className="w-full text-sm border-collapse">
+						<thead>
+							<tr className="border-b border-gray-200 dark:border-gray-700">
+								<th className="text-left py-3 pr-4"></th>
+								<th className="text-left py-3 px-4 font-semibold">PageAgent.js</th>
+								<th className="text-left py-3 pl-4 font-semibold">
+									PageAgentExt{' '}
+									<Link
+										href="/features/chrome-extension"
+										className="text-xs font-normal text-blue-600 dark:text-blue-400 hover:underline"
+									>
+										{isZh ? '了解更多' : 'learn more'}
+									</Link>
+								</th>
+							</tr>
+						</thead>
+						<tbody className="text-gray-600 dark:text-gray-300">
+							<tr className="border-b border-gray-100 dark:border-gray-800">
+								<td className="py-3 pr-4 font-medium text-gray-900 dark:text-white">
+									{isZh ? '接入方式' : 'Integration'}
+								</td>
+								<td className="py-3 px-4">
+									{isZh ? '网站开发者主动集成' : 'Site developer integrates the library'}
+								</td>
+								<td className="py-3 pl-4">
+									{isZh ? '用户安装浏览器扩展' : 'User installs a browser extension'}
+								</td>
+							</tr>
+							<tr className="border-b border-gray-100 dark:border-gray-800">
+								<td className="py-3 pr-4 font-medium text-gray-900 dark:text-white">
+									{isZh ? '可操作范围' : 'Scope'}
+								</td>
+								<td className="py-3 px-4">
+									{isZh ? '当前页面（为 SPA 设计）' : 'Current page (designed for SPAs)'}
+								</td>
+								<td className="py-3 pl-4">
+									{isZh ? '任意网页、多标签页' : 'Any web page, multi-tab'}
+								</td>
+							</tr>
+							<tr>
+								<td className="py-3 pr-4 font-medium text-gray-900 dark:text-white">
+									{isZh ? '额外能力' : 'Extra capabilities'}
+								</td>
+								<td className="py-3 px-4">—</td>
+								<td className="py-3 pl-4">
+									{isZh ? '新建/切换/关闭标签页' : 'Open / switch / close tabs'}
+								</td>
+							</tr>
+						</tbody>
+					</table>
+				</div>
+
+				{/* Interaction Limitations */}
+				<Heading id="interaction-capabilities" className="text-2xl font-bold mb-3 mt-6">
+					{isZh ? '交互能力' : 'Interaction Capabilities'}
+				</Heading>
+				<div className="bg-gray-50 dark:bg-gray-800 rounded-lg p-6 mb-6">
+					<div className="grid md:grid-cols-2 gap-6">
+						<div>
+							<h3 className="font-semibold mb-3 text-green-700 dark:text-green-400">
+								{isZh ? '支持' : 'Supported'}
+							</h3>
+							<ul className="space-y-1.5 text-sm">
+								{[
+									isZh ? '点击、文本输入、选择' : 'Click, text input, select',
+									isZh ? '页面滚动（垂直 / 水平）' : 'Scroll (vertical / horizontal)',
+									isZh ? '表单提交、焦点切换' : 'Form submit, focus',
+									isZh ? '同源 iframe（仅单层）' : 'Same-origin iframe (single level only)',
+									isZh ? '执行 JavaScript（可选）' : 'Execute JavaScript (opt-in)',
+								].map((text) => (
+									<li key={text} className="flex items-center text-gray-700 dark:text-gray-300">
+										<span className="mr-2 text-green-600 dark:text-green-400">✓</span>
+										{text}
+									</li>
+								))}
+							</ul>
+						</div>
+						<div>
+							<h3 className="font-semibold mb-3 text-red-700 dark:text-red-400">
+								{isZh ? '不支持' : 'Not supported'}
+							</h3>
+							<ul className="space-y-1.5 text-sm">
+								{[
+									isZh ? '悬停、拖拽、右键菜单' : 'Hover, drag & drop, right-click',
+									isZh ? '键盘快捷键' : 'Keyboard shortcuts',
+									isZh ? '坐标定位操作' : 'Position-based control',
+									isZh ? '嵌套 iframe、跨域 iframe' : 'Nested iframes, cross-origin iframes',
+									isZh ? '绘图操作' : 'Drawing',
+									isZh
+										? 'Monaco、CodeMirror 等需要通过 JS 实例控制的编辑器'
+										: 'Monaco, CodeMirror and other editors that require JS instance access',
+								].map((text) => (
+									<li key={text} className="flex items-center text-gray-700 dark:text-gray-300">
+										<span className="mr-2 text-red-600 dark:text-red-400">✗</span>
+										{text}
+									</li>
+								))}
+							</ul>
+						</div>
+					</div>
+				</div>
+
+				{/* Understanding Limitations */}
+				<Heading id="text-based-approach" className="text-2xl font-bold mb-3 mt-6">
+					{isZh ? '基于文本的方案' : 'Text-Based Approach'}
+				</Heading>
+
+				<p className="mb-2 font-medium">
+					{isZh
+						? 'Page Agent 不使用多模态模型，不截图，没有视觉能力。仅通过 DOM 结构理解页面。'
+						: 'Page Agent does not use multimodal models, does not take screenshots, and has no visual capability. It reads pages through DOM structure only.'}
+				</p>
+				<p className="mb-2 font-medium">
+					{isZh
+						? '图片、Canvas、WebGL、SVG 等视觉内容无法被识别。页面的语义化程度和可访问性直接影响 AI 的理解准确性。'
+						: 'Images, Canvas, WebGL, SVG and other visual content cannot be recognized. Page semantic quality and accessibility directly affect AI accuracy.'}
+				</p>
+				<p className="mb-2 font-medium">
+					{isZh
+						? '反常识的交互逻辑、纯视觉的操作提示、快速出现消失的元素等都会降低自动化成功率。语义化的 HTML 和良好的可访问性会显著提升效果。'
+						: 'Counter-intuitive interactions, visual-only cues, and rapidly appearing/disappearing elements reduce automation success. Semantic HTML and good accessibility significantly improve results.'}
+				</p>
+			</div>
+		</div>
+	)
+}
diff --git a/packages/website/src/pages/docs/introduction/overview/page.tsx b/packages/website/src/pages/docs/introduction/overview/page.tsx
new file mode 100644
index 0000000..4ebe254
--- /dev/null
+++ b/packages/website/src/pages/docs/introduction/overview/page.tsx
@@ -0,0 +1,233 @@
+import { Heading } from '@/components/Heading'
+import { useLanguage } from '@/i18n/context'
+
+export default function Overview() {
+	const { isZh } = useLanguage()
+
+	return (
+		<article>
+			<div className="mb-8">
+				<h1 className="text-4xl font-bold mb-4">Overview</h1>
+				<p className="text-xl text-gray-600 dark:text-gray-300 mb-4 leading-relaxed">
+					{isZh
+						? 'page-agent 是一个完全基于 Web 技术的 GUI Agent，简单几步，让你的网站拥有 AI 操作员。'
+						: 'page-agent is a purely web-based GUI Agent. Gives your website an AI operator in simple steps.'}
+				</p>
+
+				{/* Status Badges */}
+				<div className="flex flex-wrap gap-2 items-center">
+					<a href="https://opensource.org/licenses/MIT" target="_blank" rel="noopener noreferrer">
+						<img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="MIT License" />
+					</a>
+					<a href="http://www.typescriptlang.org/" target="_blank" rel="noopener noreferrer">
+						<img
+							src="https://img.shields.io/badge/%3C%2F%3E-TypeScript-%230074c1.svg"
+							alt="TypeScript"
+						/>
+					</a>
+					<a
+						href="https://www.npmjs.com/package/page-agent"
+						target="_blank"
+						rel="noopener noreferrer"
+					>
+						<img src="https://img.shields.io/npm/dt/page-agent.svg" alt="Downloads" />
+					</a>
+					<a
+						href="https://bundlephobia.com/package/page-agent"
+						target="_blank"
+						rel="noopener noreferrer"
+					>
+						<img src="https://img.shields.io/bundlephobia/minzip/page-agent" alt="Bundle Size" />
+					</a>
+					<a href="https://github.com/alibaba/page-agent" target="_blank" rel="noopener noreferrer">
+						<img
+							src="https://img.shields.io/github/stars/alibaba/page-agent.svg"
+							alt="GitHub stars"
+						/>
+					</a>
+				</div>
+			</div>
+
+			<section>
+				<Heading id="what-is-page-agent" className="text-2xl font-bold mb-4">
+					{isZh ? '什么是 page-agent？' : 'What is page-agent?'}
+				</Heading>
+
+				<p className="text-gray-600 dark:text-gray-300 mb-8 leading-relaxed ">
+					{isZh
+						? 'page-agent 是一个页面内嵌式 GUI Agent。与传统的浏览器自动化工具不同，page-agent 面向网站开发者，而非爬虫或Agent客户端开发者；将 Agent 集成到你的网站中，让用户可以通过自然语言与页面进行交互。'
+						: '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.'}
+				</p>
+			</section>
+
+			<section>
+				<Heading id="core-features" className="text-2xl font-bold mb-3">
+					{isZh ? '核心特性' : 'Core Features'}
+				</Heading>
+
+				<div className="grid md:grid-cols-2 gap-4 mb-8" role="list">
+					<div className="p-4 bg-blue-50 dark:bg-blue-900/20 rounded-lg">
+						<h3 className="text-lg font-semibold mb-2 text-blue-900 dark:text-blue-300">
+							{isZh ? '🧠 智能 DOM 理解' : '🧠 Smart DOM Analysis'}
+						</h3>
+						<p className="text-gray-700 dark:text-gray-300">
+							{isZh
+								? '基于 DOM 分析，高强度脱水。无需视觉识别，纯文本实现精准操作。'
+								: 'DOM-based analysis with high-intensity dehydration. No visual recognition needed. Pure text for fast and precise operations.'}
+						</p>
+					</div>
+
+					<div className="p-4 bg-purple-50 dark:bg-purple-900/20 rounded-lg">
+						<h3 className="text-lg font-semibold mb-2 text-purple-900 dark:text-purple-300">
+							{isZh ? '🔒 安全可控' : '🔒 Secure & Controllable'}
+						</h3>
+						<p className="text-gray-700 dark:text-gray-300">
+							{isZh
+								? '支持操作黑白名单、数据脱敏保护。注入自定义知识库，让 AI 按你的规则工作。'
+								: 'Supports operation allowlists, data masking protection. Inject custom knowledge to make AI work by your rules.'}
+						</p>
+					</div>
+
+					<div className="p-4 bg-green-50 dark:bg-green-900/20 rounded-lg">
+						<h3 className="text-lg font-semibold mb-2 text-green-900 dark:text-green-300">
+							{isZh ? '⚡ 零后端部署' : '⚡ Zero Backend'}
+						</h3>
+						<p className="text-gray-700 dark:text-gray-300">
+							{isZh
+								? 'CDN 或 NPM 引入，自定义 LLM 接入点。'
+								: 'CDN or NPM import with custom LLM endpoints.'}
+						</p>
+					</div>
+
+					<div className="p-4 bg-orange-50 dark:bg-orange-900/20 rounded-lg">
+						<h3 className="text-lg font-semibold mb-2 text-orange-900 dark:text-orange-300">
+							{isZh ? '♿ 普惠智能' : '♿ Accessible Intelligence'}
+						</h3>
+						<p className="text-gray-700 dark:text-gray-300">
+							{isZh
+								? '为复杂 B端系统、管理后台提供自然语言入口。让每个用户都能轻松上手。'
+								: 'Provides natural language interface for complex B2B systems and admin panels. Makes software easy for everyone.'}
+						</p>
+					</div>
+				</div>
+
+				<Heading id="vs-browser-use" className="text-2xl font-bold mb-4">
+					{isZh ? '与 browser-use 的区别' : 'vs. browser-use'}
+				</Heading>
+
+				<div className="overflow-x-auto mb-8">
+					<table className="w-full border-collapse border border-gray-300 dark:border-gray-600">
+						<thead>
+							<tr className="bg-gray-50 dark:bg-gray-800">
+								<th className="border border-gray-300 dark:border-gray-600 px-4 py-3 text-left"></th>
+								<th className="border border-gray-300 dark:border-gray-600 px-4 py-3 text-left">
+									page-agent
+								</th>
+								<th className="border border-gray-300 dark:border-gray-600 px-4 py-3 text-left">
+									browser-use
+								</th>
+							</tr>
+						</thead>
+						<tbody>
+							<tr>
+								<td className="border border-gray-300 dark:border-gray-600 px-4 py-3 font-medium">
+									{isZh ? '部署方式' : 'Deployment'}
+								</td>
+								<td className="border border-gray-300 dark:border-gray-600 px-4 py-3">
+									{isZh ? '页面内嵌组件' : 'Embedded component'}
+								</td>
+								<td className="border border-gray-300 dark:border-gray-600 px-4 py-3">
+									{isZh ? '外部工具' : 'External tool'}
+								</td>
+							</tr>
+							<tr>
+								<td className="border border-gray-300 dark:border-gray-600 px-4 py-3 font-medium">
+									{isZh ? '操作范围' : 'Scope'}
+								</td>
+								<td className="border border-gray-300 dark:border-gray-600 px-4 py-3">
+									{isZh ? '当前页面' : 'Current page'}
+								</td>
+								<td className="border border-gray-300 dark:border-gray-600 px-4 py-3">
+									{isZh ? '整个浏览器' : 'Entire browser'}
+								</td>
+							</tr>
+							<tr>
+								<td className="border border-gray-300 dark:border-gray-600 px-4 py-3 font-medium">
+									{isZh ? '目标用户' : 'Target Users'}
+								</td>
+								<td className="border border-gray-300 dark:border-gray-600 px-4 py-3">
+									{isZh ? '网站开发者' : 'Web developers'}
+								</td>
+								<td className="border border-gray-300 dark:border-gray-600 px-4 py-3">
+									{isZh ? '爬虫/Agent 开发者' : 'Scraper/Agent developers'}
+								</td>
+							</tr>
+							<tr>
+								<td className="border border-gray-300 dark:border-gray-600 px-4 py-3 font-medium">
+									{isZh ? '使用场景' : 'Use Case'}
+								</td>
+								<td className="border border-gray-300 dark:border-gray-600 px-4 py-3">
+									{isZh ? '用户体验增强' : 'UX enhancement'}
+								</td>
+								<td className="border border-gray-300 dark:border-gray-600 px-4 py-3">
+									{isZh ? '自动化任务' : 'Automation tasks'}
+								</td>
+							</tr>
+						</tbody>
+					</table>
+				</div>
+
+				<Heading id="use-cases" className="text-2xl font-bold mb-4">
+					{isZh ? '应用场景' : 'Use Cases'}
+				</Heading>
+
+				<ul className="space-y-4 mb-8">
+					<li className="flex items-start space-x-3">
+						<span className="w-6 h-6 min-w-6 bg-blue-500 text-white rounded-full flex items-center justify-center font-bold text-sm mt-0.5 shrink-0">
+							1
+						</span>
+						<div className="text-gray-700 dark:text-gray-300">
+							<strong>{isZh ? '对接答疑机器人：' : 'Connect Support Bots:'}</strong>{' '}
+							{isZh
+								? '把你的答疑助手变成全能Agent。客服机器人不再只说「请先点击设置按钮然后点击...」，而是直接帮用户现场操作。'
+								: "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."}
+						</div>
+					</li>
+					<li className="flex items-start space-x-3">
+						<span className="w-6 h-6 min-w-6 bg-green-500 text-white rounded-full flex items-center justify-center font-bold text-sm mt-0.5 shrink-0">
+							2
+						</span>
+						<div className="text-gray-700 dark:text-gray-300">
+							<strong>{isZh ? '交互升级/智能化改造：' : 'Modernize Legacy Apps:'}</strong>{' '}
+							{isZh
+								? '一行代码，老应用变身Agent，产品专家帮用户操作复杂 B 端软件。降低人工支持成本，提高用户满意度。'
+								: 'One line of code transforms old apps into agents. Product experts help users navigate complex B2B software. Reduce support costs and improve satisfaction.'}
+						</div>
+					</li>
+					<li className="flex items-start space-x-3">
+						<span className="w-6 h-6 min-w-6 bg-purple-500 text-white rounded-full flex items-center justify-center font-bold text-sm mt-0.5 shrink-0">
+							3
+						</span>
+						<div className="text-gray-700 dark:text-gray-300">
+							<strong>{isZh ? '产品教学：' : 'Interactive Training:'}</strong>{' '}
+							{isZh
+								? '向用户演示交互过程，边做边教。例如让AI演示「如何提交报销申请」的完整操作流程。'
+								: "Demonstrate workflows in real-time. Let AI show the complete process of 'how to submit an expense report.'"}
+						</div>
+					</li>
+					<li className="flex items-start space-x-3">
+						<span className="w-6 h-6 min-w-6 bg-orange-500 text-white rounded-full flex items-center justify-center font-bold text-sm mt-0.5 shrink-0">
+							4
+						</span>
+						<div className="text-gray-700 dark:text-gray-300">
+							<strong>{isZh ? '无障碍支持：' : 'Accessibility:'}</strong>{' '}
+							{isZh
+								? '为视障用户、老年用户提供自然语言交互，对接屏幕阅读器或语音助理，让软件人人可用。'
+								: 'Provide natural language interaction for visually impaired and elderly users. Connect screen readers or voice assistants to make software accessible to everyone.'}
+						</div>
+					</li>
+				</ul>
+			</section>
+		</article>
+	)
+}
diff --git a/packages/website/src/pages/docs/introduction/quick-start/page.tsx b/packages/website/src/pages/docs/introduction/quick-start/page.tsx
new file mode 100644
index 0000000..7d0aa9a
--- /dev/null
+++ b/packages/website/src/pages/docs/introduction/quick-start/page.tsx
@@ -0,0 +1,134 @@
+import CodeEditor from '@/components/CodeEditor'
+import { Heading } from '@/components/Heading'
+import { CDN_DEMO_CN_URL, CDN_DEMO_URL } from '@/constants'
+import { useLanguage } from '@/i18n/context'
+
+export default function QuickStart() {
+	const { isZh } = useLanguage()
+
+	return (
+		<div>
+			<h1 className="text-4xl font-bold mb-6">Quick Start</h1>
+
+			<p className=" mb-6 leading-relaxed">
+				{isZh ? '几分钟内完成 page-agent 的集成。' : 'Integrate page-agent in minutes.'}
+			</p>
+
+			<Heading id="installation-steps" className="text-2xl font-bold mb-3">
+				{isZh ? '安装步骤' : 'Installation Steps'}
+			</Heading>
+
+			<div className="space-y-4 mb-6">
+				{/* Demo CDN - One Line */}
+				<div className="p-4 bg-blue-50 dark:bg-blue-900/20 rounded-lg">
+					<h3 className="text-lg font-semibold mb-2 text-blue-900 dark:text-blue-300">
+						{isZh ? '🚀 快速体验（Demo CDN）' : '🚀 Quick Try (Demo CDN)'}
+					</h3>
+					<div className="bg-yellow-50 dark:bg-yellow-900/20 p-2 rounded mb-3 text-sm">
+						<span className="text-yellow-800 dark:text-yellow-200">
+							⚠️{' '}
+							{isZh ? (
+								<>
+									该 Demo CDN 使用了免费的测试 LLM API，使用即表示您同意其
+									<a
+										href="https://github.com/alibaba/page-agent/blob/main/docs/terms-and-privacy.md#2-testing-api-and-demo-disclaimer--terms-of-use"
+										target="_blank"
+										rel="noopener noreferrer"
+										className="underline"
+									>
+										使用条款
+									</a>
+								</>
+							) : (
+								<>
+									This demo CDN uses our free testing LLM API. By using it you agree to the{' '}
+									<a
+										href="https://github.com/alibaba/page-agent/blob/main/docs/terms-and-privacy.md#2-testing-api-and-demo-disclaimer--terms-of-use"
+										target="_blank"
+										rel="noopener noreferrer"
+										className="underline"
+									>
+										Terms of Use
+									</a>
+								</>
+							)}
+						</span>
+					</div>
+					<CodeEditor
+						code={`<script src="DEMO_CDN_URL" crossorigin="true"></script>`}
+						language="html"
+					/>
+					<p className="text-sm text-gray-600 dark:text-gray-300 mb-3">
+						{isZh
+							? '在 URL 后添加 ?autoInit=false 可只加载脚本，不自动创建 Demo Agent；之后可通过 new window.PageAgent(...) 手动初始化。'
+							: 'Add ?autoInit=false to load the script without creating the demo agent automatically. You can then instantiate it with new window.PageAgent(...).'}
+					</p>
+					<table className="w-full border-collapse text-sm">
+						<thead>
+							<tr className="border-b border-gray-200 dark:border-gray-700">
+								<th className="text-left py-2 px-3 font-semibold w-28">
+									{isZh ? '镜像' : 'Mirrors'}
+								</th>
+								<th className="text-left py-2 px-3 font-semibold">URL</th>
+							</tr>
+						</thead>
+						<tbody>
+							<tr className="border-b border-gray-100 dark:border-gray-800">
+								<td className="py-2 px-3">{isZh ? '全球' : 'Global'}</td>
+								<td className="py-2 px-3 font-mono text-xs break-all">{CDN_DEMO_URL}</td>
+							</tr>
+							<tr>
+								<td className="py-2 px-3">{isZh ? '中国' : 'China'}</td>
+								<td className="py-2 px-3 font-mono text-xs break-all">{CDN_DEMO_CN_URL}</td>
+							</tr>
+						</tbody>
+					</table>
+				</div>
+
+				{/* NPM - Recommended */}
+				<div className="p-4 bg-green-50 dark:bg-green-900/20 rounded-lg">
+					<h3 className="text-lg font-semibold mb-2 text-green-900 dark:text-green-300">
+						{isZh ? '📦 NPM 安装（推荐）' : '📦 NPM Install (Recommended)'}
+					</h3>
+					<CodeEditor
+						code={`// npm install page-agent
+
+import { PageAgent } from 'page-agent'`}
+						language="bash"
+					/>
+				</div>
+
+				<div className="p-4 bg-purple-50 dark:bg-purple-900/20 rounded-lg">
+					<h3 className="text-lg font-semibold mb-2 text-purple-900 dark:text-purple-300">
+						{isZh ? '2. 初始化配置' : '2. Initialize Configuration'}
+					</h3>
+					<CodeEditor
+						code={`const agent = new PageAgent({
+  model: 'qwen3.5-plus',
+  baseURL: 'https://dashscope.aliyuncs.com/compatible-mode/v1',
+  apiKey: 'YOUR_API_KEY',
+  language: '${isZh ? 'zh-CN' : 'en-US'}'
+})`}
+						language="javascript"
+					/>
+				</div>
+
+				<div className="p-4 bg-orange-50 dark:bg-orange-900/20 rounded-lg">
+					<h3 className="text-lg font-semibold mb-2 text-orange-900 dark:text-orange-300">
+						{isZh ? '3. 开始使用' : '3. Start Using'}
+					</h3>
+					<CodeEditor
+						code={`// ${isZh ? '程序化执行自然语言指令' : 'Execute natural language instructions programmatically'}
+await agent.execute('${isZh ? '点击提交按钮，然后填写用户名为张三' : 'Click submit button, then fill username as John'}');
+
+// ${isZh ? '或者' : 'Or:'}
+// ${isZh ? '显示对话框让用户输入指令' : 'Show panel for user to input instructions'}
+agent.panel.show()
+`}
+						language="javascript"
+					/>
+				</div>
+			</div>
+		</div>
+	)
+}
diff --git a/packages/website/src/pages/docs/introduction/troubleshooting/page.tsx b/packages/website/src/pages/docs/introduction/troubleshooting/page.tsx
new file mode 100644
index 0000000..633f47f
--- /dev/null
+++ b/packages/website/src/pages/docs/introduction/troubleshooting/page.tsx
@@ -0,0 +1,430 @@
+import { useEffect, useRef, useState } from 'react'
+import { Link } from 'wouter'
+
+import CodeEditor from '@/components/CodeEditor'
+import { Heading } from '@/components/Heading'
+import { useLanguage } from '@/i18n/context'
+
+// ---------------------------------------------------------------------------
+// Data: each section is a typed object for easy extension
+// ---------------------------------------------------------------------------
+
+interface TroubleshootingSection {
+	id: string
+	title: { en: string; zh: string }
+	symptom: { en: string; zh: string }
+	color: 'red' | 'amber' | 'orange' | 'violet'
+	content: (isZh: boolean) => React.ReactNode
+}
+
+const SECTIONS: TroubleshootingSection[] = [
+	{
+		id: 'format-errors',
+		title: { en: 'Model Response Format Errors', zh: '模型返回格式错误' },
+		symptom: {
+			en: 'The model returns malformed tool calls, plain text, or unexpected JSON instead of structured actions.',
+			zh: '模型返回了格式错误的 tool call、纯文本或非预期的 JSON，而非结构化的操作指令。',
+		},
+		color: 'amber',
+		content: FormatErrorsContent,
+	},
+	{
+		id: 'low-success-rate',
+		title: { en: 'Low Task Success Rate', zh: '任务成功率低' },
+		symptom: {
+			en: 'The agent appears to understand the task but frequently fails to complete it, or produces incorrect results.',
+			zh: 'Agent 似乎理解了任务，但频繁执行失败或产生不正确的结果。',
+		},
+		color: 'amber',
+		content: LowSuccessRateContent,
+	},
+	{
+		id: 'wrong-element',
+		title: { en: "Can't Hit Target Elements", zh: '无法点击目标元素' },
+		symptom: {
+			en: 'The agent repeatedly retries but keeps interacting with the wrong element, or fails to locate the correct one.',
+			zh: 'Agent 反复重试，但始终点击在错误的元素上，或无法定位到正确的目标元素。',
+		},
+		color: 'amber',
+		content: WrongElementContent,
+	},
+	{
+		id: 'api-errors',
+		title: { en: 'API Request Errors', zh: 'API 请求错误' },
+		symptom: {
+			en: 'HTTP 400 Bad Request or similar errors when calling the LLM API.',
+			zh: '调用 LLM API 时出现 HTTP 400 Bad Request 或类似的参数错误。',
+		},
+		color: 'amber',
+		content: ApiErrorsContent,
+	},
+]
+
+// ---------------------------------------------------------------------------
+// Section content components
+// ---------------------------------------------------------------------------
+
+function FormatErrorsContent(isZh: boolean) {
+	return (
+		<ol className="list-decimal pl-5 space-y-4 text-gray-700 dark:text-gray-300">
+			<li>
+				<strong>{isZh ? '确认模型是否支持' : 'Verify model compatibility'}</strong>
+				<p className="mt-1">
+					{isZh
+						? '并非所有模型都能正确处理 page-agent 的 tool 定义。请查看'
+						: 'Not all models can handle page-agent tool definitions correctly. Check the '}
+					<Link
+						href="/features/models"
+						className="text-blue-600 dark:text-blue-400 underline underline-offset-2"
+					>
+						{isZh ? '已测试模型列表' : 'tested models list'}
+					</Link>
+					{isZh ? '。' : '.'}
+				</p>
+			</li>
+			<li>
+				<strong>
+					{isZh ? '检查代理/网关的参数转发' : 'Check proxy/gateway parameter forwarding'}
+				</strong>
+				<p className="mt-1">
+					{isZh
+						? '如果使用了 API 代理或网关，请确保请求中的 '
+						: 'If using an API proxy or gateway, make sure the '}
+					<code>tools</code>
+					{isZh
+						? ' 字段被完整、无修改地转发给模型供应商。部分代理可能会剥离或修改此字段。'
+						: ' parameter is forwarded to the model provider intact. Some proxies may strip or alter this field.'}
+				</p>
+			</li>
+			<li>
+				<strong>{isZh ? '寻求社区帮助' : 'Get community help'}</strong>
+				<p className="mt-1">
+					{isZh ? (
+						<>
+							如果以上步骤无法解决问题，欢迎在{' '}
+							<a
+								href="https://github.com/alibaba/page-agent/issues"
+								target="_blank"
+								rel="noopener noreferrer"
+								className="text-blue-600 dark:text-blue-400 underline underline-offset-2"
+							>
+								GitHub Issues
+							</a>{' '}
+							中反馈，附上模型名称和错误信息。
+						</>
+					) : (
+						<>
+							If the above steps don't help, open a{' '}
+							<a
+								href="https://github.com/alibaba/page-agent/issues"
+								target="_blank"
+								rel="noopener noreferrer"
+								className="text-blue-600 dark:text-blue-400 underline underline-offset-2"
+							>
+								GitHub Issue
+							</a>{' '}
+							with your model name and error details.
+						</>
+					)}
+				</p>
+			</li>
+		</ol>
+	)
+}
+
+function LowSuccessRateContent(isZh: boolean) {
+	return (
+		<>
+			<p className="text-sm text-gray-500 dark:text-gray-400 mb-4 italic">
+				{isZh
+					? '按以下顺序逐步排查，从最简单的情况开始：'
+					: 'Follow this diagnostic funnel from simplest to most advanced:'}
+			</p>
+			<ol className="list-decimal pl-5 space-y-4 text-gray-700 dark:text-gray-300">
+				<li>
+					<strong>{isZh ? '先从简单指令开始' : 'Start with a simple instruction'}</strong>
+					<p className="mt-1">
+						{isZh
+							? '给一个具体的、单步的简单指令（如"点击登录按钮"），看 Agent 能否完成。如果连简单操作都失败了，问题可能不在模型能力上。'
+							: 'Give a concrete, single-step instruction (e.g. "click the login button"). If even simple actions fail, the issue is likely not model capability.'}
+					</p>
+				</li>
+				<li>
+					<strong>{isZh ? '尝试最强模型' : 'Try the strongest model available'}</strong>
+					<p className="mt-1">
+						{isZh
+							? '切换到你能获取到的最先进、最大的模型，以排除是否是模型智能水平不足导致的问题。'
+							: "Switch to the most capable model you have access to, to isolate whether it's a model intelligence issue."}
+					</p>
+				</li>
+				<li>
+					<strong>{isZh ? '优化指令质量' : 'Improve instruction quality'}</strong>
+					<p className="mt-1">
+						{isZh
+							? '给出尽可能具体的指令。对于复杂任务，建议使用另一个 LLM 来预先拆分和细化用户的需求，然后逐步执行。'
+							: "Be as specific as possible. For complex tasks, consider using another LLM to decompose and refine the user's request before execution."}
+					</p>
+				</li>
+				<li>
+					<strong>{isZh ? '提供充足的上下文' : 'Provide sufficient context'}</strong>
+					<p className="mt-1">
+						{isZh
+							? '通过 instructions 配置注入网站背景描述、关键术语解释等上下文信息，帮助 Agent 更好地理解页面。'
+							: 'Use the instructions config to inject website descriptions, key terminology, and background context to help the agent understand the page.'}
+					</p>
+				</li>
+				<li>
+					<strong>{isZh ? '检查 HTML 清洗结果' : 'Check HTML sanitization output'}</strong>
+					<p className="mt-1">
+						{isZh
+							? '使用开发者工具检查清洗后的 HTML，确认关键信息、文本和可操作元素是否被正确保留。'
+							: 'Inspect the sanitized HTML in dev tools to confirm that key information, text, and interactive elements are preserved correctly.'}
+					</p>
+				</li>
+			</ol>
+		</>
+	)
+}
+
+function WrongElementContent(isZh: boolean) {
+	return (
+		<ol className="list-decimal pl-5 space-y-4 text-gray-700 dark:text-gray-300">
+			<li>
+				<strong>{isZh ? '了解现实局限' : 'Understand the reality'}</strong>
+				<p className="mt-1">
+					{isZh
+						? '并非所有网站都提供了完善的语义化 HTML 和 accessibility 标签。对于此类网站，DOM 清洗可能无法产出足够好的结果。'
+						: 'Not all websites provide proper semantic HTML and accessibility labels. For such sites, DOM sanitization may not produce good enough results.'}
+				</p>
+			</li>
+			<li>
+				<strong>{isZh ? '检查目标元素类型' : 'Check target element type'}</strong>
+				<p className="mt-1">
+					{isZh
+						? '确认目标元素是否为图片、Canvas、或需要复杂交互（如拖拽、基于坐标的点击）的元素。这些本身就超出了当前的能力范围。'
+						: 'Verify if the target is an image, Canvas, or requires complex interactions (drag-and-drop, coordinate-based clicking). These are beyond current capabilities.'}
+				</p>
+			</li>
+			<li>
+				<strong>{isZh ? '检查清洗后的 HTML' : 'Inspect sanitized HTML'}</strong>
+				<p className="mt-1">
+					{isZh
+						? '检查清洗结果中是否存在关键信息丢失、可操作元素未被编号等问题。'
+						: 'Look for missing key information or unnumbered interactive elements in the sanitized output.'}
+				</p>
+			</li>
+			<li>
+				<strong>{isZh ? '注入 accessibility 增强' : 'Inject accessibility improvements'}</strong>
+				<p className="mt-1">
+					{isZh
+						? '通过注入脚本为网站添加 aria-label、语义化标签等 accessibility 属性，改善 DOM 清洗质量。'
+						: 'Inject scripts to add aria-labels, semantic attributes, and other a11y improvements to enhance DOM sanitization quality.'}
+				</p>
+			</li>
+			<li>
+				<strong>{isZh ? '开发专用 Tool' : 'Build a custom Tool'}</strong>
+				<p className="mt-1">
+					{isZh ? (
+						<>
+							对于特定的、持续难以操作的元素，考虑开发{' '}
+							<Link
+								href="/features/custom-tools"
+								className="text-blue-600 dark:text-blue-400 underline underline-offset-2"
+							>
+								自定义 Tool
+							</Link>{' '}
+							来直接操作这些元素。
+						</>
+					) : (
+						<>
+							For consistently difficult elements, consider building a{' '}
+							<Link
+								href="/features/custom-tools"
+								className="text-blue-600 dark:text-blue-400 underline underline-offset-2"
+							>
+								custom Tool
+							</Link>{' '}
+							to interact with them directly.
+						</>
+					)}
+				</p>
+			</li>
+		</ol>
+	)
+}
+
+function ApiErrorsContent(isZh: boolean) {
+	return (
+		<div className="space-y-4 text-gray-700 dark:text-gray-300">
+			<p>
+				{isZh
+					? '一些 LLM 供应商使用了与 OpenAI 不完全兼容的参数格式，导致请求参数校验失败。'
+					: 'Some LLM providers use parameter formats that are not fully compatible with the OpenAI spec, causing request validation failures.'}
+			</p>
+			<div className="bg-gray-50 dark:bg-gray-800/50 rounded-lg p-4">
+				<p className="font-medium mb-2">
+					{isZh ? '解决方案：使用 customFetch' : 'Solution: use customFetch'}
+				</p>
+				<p className="text-sm mb-3">
+					{isZh
+						? '通过 customFetch 配置拦截请求，在发送前调整参数格式以适配目标供应商的要求。'
+						: 'Use the customFetch config to intercept requests and adapt parameters before sending them to the target provider.'}
+				</p>
+				<CodeEditor
+					code={`const agent = new PageAgent({
+  // ...
+  customFetch: async (url, init) => {
+    // Adapt parameters for your provider
+    const body = JSON.parse(init.body)
+    delete body.tool_choice
+    const bodyStr = JSON.stringify(body)
+
+    return fetch(url, { ...init, body: bodyStr })
+  },
+})`}
+				/>
+			</div>
+			<p className="text-sm">
+				{isZh ? '参见 ' : 'See '}
+				<Link
+					href="/advanced/page-agent-core"
+					className="text-blue-600 dark:text-blue-400 underline underline-offset-2"
+				>
+					PageAgentCore API
+				</Link>
+				{isZh ? ' 了解 customFetch 的完整用法。' : ' for full customFetch documentation.'}
+			</p>
+		</div>
+	)
+}
+
+// ---------------------------------------------------------------------------
+// Color mapping for symptom callouts
+// ---------------------------------------------------------------------------
+
+const SYMPTOM_COLORS = {
+	red: 'border-red-400 bg-red-50 dark:bg-red-900/15 text-red-800 dark:text-red-200',
+	amber: 'border-amber-400 bg-amber-50 dark:bg-amber-900/15 text-amber-800 dark:text-amber-200',
+	orange:
+		'border-orange-400 bg-orange-50 dark:bg-orange-900/15 text-orange-800 dark:text-orange-200',
+	violet:
+		'border-violet-400 bg-violet-50 dark:bg-violet-900/15 text-violet-800 dark:text-violet-200',
+} as const
+
+// ---------------------------------------------------------------------------
+// Right-side TOC with IntersectionObserver
+// ---------------------------------------------------------------------------
+
+function useActiveSection(ids: string[]) {
+	const [activeId, setActiveId] = useState(ids[0])
+	const observerRef = useRef<IntersectionObserver | null>(null)
+
+	useEffect(() => {
+		observerRef.current?.disconnect()
+
+		const visibleEntries = new Map<string, number>()
+
+		observerRef.current = new IntersectionObserver(
+			(entries) => {
+				for (const entry of entries) {
+					if (entry.isIntersecting) {
+						visibleEntries.set(entry.target.id, entry.intersectionRatio)
+					} else {
+						visibleEntries.delete(entry.target.id)
+					}
+				}
+				// Pick the first visible section in document order
+				const firstVisible = ids.find((id) => visibleEntries.has(id))
+				if (firstVisible) setActiveId(firstVisible)
+			},
+			{ rootMargin: '-80px 0px -60% 0px', threshold: [0, 0.25] }
+		)
+
+		for (const id of ids) {
+			const el = document.getElementById(id)
+			if (el) observerRef.current.observe(el)
+		}
+
+		return () => observerRef.current?.disconnect()
+	}, [ids])
+
+	return activeId
+}
+
+// ---------------------------------------------------------------------------
+// Page component
+// ---------------------------------------------------------------------------
+
+export default function TroubleshootingPage() {
+	const { isZh } = useLanguage()
+	const sectionIds = SECTIONS.map((s) => s.id)
+	const activeId = useActiveSection(sectionIds)
+
+	return (
+		<div className="max-w-5xl mx-auto">
+			{/* Header */}
+			<div className="mb-10">
+				<h1 className="text-4xl font-bold mb-4 text-gray-900 dark:text-white">Troubleshooting</h1>
+			</div>
+
+			{/* Two-column: content + TOC */}
+			<div className="flex gap-8">
+				{/* Main content */}
+				<div className="flex-1 min-w-0 space-y-12">
+					{SECTIONS.map((section) => (
+						<section key={section.id} className="scroll-mt-24">
+							<Heading
+								id={section.id}
+								className="text-2xl font-bold mb-4 text-gray-900 dark:text-white"
+							>
+								{isZh ? section.title.zh : section.title.en}
+							</Heading>
+
+							{/* Symptom callout */}
+							<div
+								className={`border-l-4 px-4 py-3 rounded-r-lg mb-6 ${SYMPTOM_COLORS[section.color]}`}
+							>
+								<span className="text-xs font-semibold uppercase tracking-wider opacity-70">
+									{isZh ? '症状' : 'Symptom'}
+								</span>
+								<p className="mt-1 text-sm">{isZh ? section.symptom.zh : section.symptom.en}</p>
+							</div>
+
+							{/* Diagnostic steps */}
+							<div className="prose-sm">{section.content(isZh)}</div>
+						</section>
+					))}
+				</div>
+
+				{/* Right TOC */}
+				<aside className="hidden lg:block w-48 shrink-0">
+					<div className="sticky top-24">
+						<h4 className="text-xs font-semibold text-gray-400 dark:text-gray-500 uppercase tracking-wider mb-3">
+							{isZh ? '目录' : 'On this page'}
+						</h4>
+						<nav className="space-y-1">
+							{SECTIONS.map((section) => (
+								<button
+									key={section.id}
+									type="button"
+									onClick={() =>
+										document
+											.getElementById(section.id)
+											?.scrollIntoView({ behavior: 'smooth', block: 'start' })
+									}
+									className={`block cursor-pointer py-1 text-left text-sm transition-colors ${
+										activeId === section.id
+											? 'text-blue-600 dark:text-blue-400 font-medium'
+											: 'text-gray-500 dark:text-gray-400 hover:text-gray-900 dark:hover:text-gray-200'
+									}`}
+								>
+									{isZh ? section.title.zh : section.title.en}
+								</button>
+							))}
+						</nav>
+					</div>
+				</aside>
+			</div>
+		</div>
+	)
+}
diff --git a/packages/website/src/pages/home/FeaturesSection.tsx b/packages/website/src/pages/home/FeaturesSection.tsx
new file mode 100644
index 0000000..8e91e7f
--- /dev/null
+++ b/packages/website/src/pages/home/FeaturesSection.tsx
@@ -0,0 +1,233 @@
+import { Bot, Box, MessageSquare, Shield, Sparkles, Users } from 'lucide-react'
+
+import { BlurFade } from '../../components/ui/blur-fade'
+import { Highlighter } from '../../components/ui/highlighter'
+import { MagicCard } from '../../components/ui/magic-card'
+import { Particles } from '../../components/ui/particles'
+import { useLanguage } from '../../i18n/context'
+
+// Word-cloud style: each item has a position (%), size, opacity, and color for a scattered look
+const LLM_CLOUD: {
+	name: string
+	color: string
+	x: number
+	y: number
+	size: number
+	opacity: number
+}[] = [
+	{ name: 'OpenAI', color: '#10b981', x: 18, y: 22, size: 1.5, opacity: 1 },
+	{ name: 'Claude', color: '#f97316', x: 58, y: 15, size: 1.35, opacity: 0.95 },
+	{ name: 'Qwen', color: '#8b5cf6', x: 35, y: 50, size: 1.8, opacity: 0.9 },
+	{ name: 'Gemini', color: '#3b82f6', x: 72, y: 48, size: 1.2, opacity: 0.85 },
+	{ name: 'DeepSeek', color: '#06b6d4', x: 13, y: 65, size: 1.1, opacity: 0.8 },
+	{ name: 'Grok', color: '#f43f5e', x: 52, y: 78, size: 1.0, opacity: 0.75 },
+	{ name: 'Ollama', color: '#9ca3af', x: 84, y: 25, size: 1.1, opacity: 0.8 },
+	{ name: 'LM Studio', color: '#4338ca', x: 49, y: 36, size: 0.8, opacity: 0.9 },
+	{ name: 'Kimi', color: '#14b8a6', x: 30, y: 82, size: 0.85, opacity: 0.6 },
+	{ name: 'GLM', color: '#f59e0b', x: 70, y: 72, size: 0.85, opacity: 0.55 },
+	{ name: 'LLaMA', color: '#60a5fa', x: 88, y: 70, size: 0.8, opacity: 0.45 },
+]
+
+const CARD_HEIGHT = 'h-72'
+
+export default function FeaturesSection() {
+	const { isZh } = useLanguage()
+
+	return (
+		<section className="px-6 py-14" aria-labelledby="features-heading">
+			<div className="max-w-6xl mx-auto">
+				<div className="grid grid-cols-1 md:grid-cols-3 gap-4 auto-rows-[18rem]">
+					{/* Row 1: Zero Infrastructure (2col) + Privacy (1col) */}
+					<BlurFade inView className="col-span-1 md:col-span-2">
+						<MagicCard
+							className="h-full rounded-2xl"
+							gradientFrom="#3b82f6"
+							gradientTo="#06b6d4"
+							gradientColor="#3b82f6"
+							gradientOpacity={0.15}
+						>
+							<div className={`flex ${CARD_HEIGHT} flex-col`}>
+								<div className="flex-1 p-7 flex flex-col justify-center">
+									<div className="space-y-2.5 mb-5">
+										{[
+											'pip install browser-use playwright',
+											'docker run -p 3000:3000 playwright-mcp',
+											'const browser = await chromium.launch()',
+										].map((cmd) => (
+											<div
+												key={cmd}
+												className="font-mono text-sm text-white-400 dark:text-gray-300 truncate"
+											>
+												<Highlighter
+													action="strike-through"
+													color="#ef4444aa"
+													strokeWidth={1.5}
+													// multiline={false}
+													// isView
+												>
+													{cmd}
+												</Highlighter>
+											</div>
+										))}
+									</div>
+									<div className="bg-emerald-50 dark:bg-emerald-950/30 border border-emerald-200/60 dark:border-emerald-700/40 rounded-xl px-5 py-3 font-mono text-sm text-emerald-700 dark:text-emerald-400 flex items-center gap-2.5">
+										<span className="text-emerald-500 text-xs shrink-0">✓</span>
+										{'<script src="page-agent.js"></script>'}
+									</div>
+								</div>
+								<div className="px-7 pb-5">
+									<div className="flex items-center gap-2.5 mb-1">
+										<Box className="w-5 h-5 text-blue-500" />
+										<h3 className="font-semibold text-lg text-gray-900 dark:text-white">
+											{isZh ? '零基建集成' : 'Zero Infrastructure'}
+										</h3>
+									</div>
+									<p className="text-sm text-gray-500 dark:text-gray-300 leading-relaxed">
+										{isZh
+											? '无需 Python、无头浏览器、服务端部署。一行 script 标签搞定。'
+											: "No Python. No headless browser. No server. One script tag — that's it."}
+									</p>
+								</div>
+							</div>
+						</MagicCard>
+					</BlurFade>
+
+					<BlurFade inView delay={0.1} className="col-span-1">
+						<MagicCard
+							className="h-full rounded-2xl"
+							gradientFrom="#8b5cf6"
+							gradientTo="#a855f7"
+							gradientColor="#8b5cf6"
+							gradientOpacity={0.12}
+						>
+							<div className={`flex ${CARD_HEIGHT} flex-col`}>
+								<div className="flex-1 relative overflow-hidden">
+									<Particles
+										className="absolute inset-0"
+										quantity={40}
+										staticity={50}
+										ease={80}
+										color="#8b5cf6"
+									/>
+									<div className="absolute inset-0 flex items-center justify-center">
+										<div className="w-16 h-16 rounded-2xl bg-purple-500/10 dark:bg-purple-500/20 backdrop-blur-sm flex items-center justify-center ring-1 ring-purple-500/20">
+											<Shield className="w-8 h-8 text-purple-500" strokeWidth={1.5} />
+										</div>
+									</div>
+								</div>
+								<div className="px-6 pb-5">
+									<h3 className="font-semibold text-lg text-gray-900 dark:text-white mb-1">
+										{isZh ? '隐私优先' : 'Privacy by Default'}
+									</h3>
+									<p className="text-sm text-gray-500 dark:text-gray-300 leading-relaxed">
+										{isZh
+											? '浏览器内运行，数据完全由你掌控。'
+											: 'Runs in the browser. You control your data, always.'}
+									</p>
+								</div>
+							</div>
+						</MagicCard>
+					</BlurFade>
+
+					{/* Row 2: Human-in-the-Loop (1col) + LLM (2col) */}
+					<BlurFade inView delay={0.15} className="col-span-1">
+						<MagicCard
+							className="h-full rounded-2xl"
+							gradientFrom="#3b82f6"
+							gradientTo="#8b5cf6"
+							gradientColor="#6366f1"
+							gradientOpacity={0.12}
+						>
+							<div className={`flex ${CARD_HEIGHT} flex-col`}>
+								<div className="flex-1 p-5 flex flex-col justify-center max-w-xs mx-auto w-full">
+									<div className="flex gap-2 mb-2.5">
+										<div className="shrink-0 w-6 h-6 rounded-full bg-purple-100 dark:bg-purple-900/50 flex items-center justify-center">
+											<Bot className="w-3.5 h-3.5 text-purple-600 dark:text-purple-400" />
+										</div>
+										<div className="bg-gray-100 dark:bg-white/10 rounded-2xl rounded-tl-md px-3.5 py-2 text-sm text-gray-700 dark:text-gray-200">
+											{isZh ? '找到 3 条匹配记录。选择哪一条？' : 'Found 3 matches. Which one?'}
+										</div>
+									</div>
+									<div className="flex gap-2 justify-end mb-2.5">
+										<div className="bg-blue-500 rounded-2xl rounded-tr-md px-3.5 py-2 text-sm text-white">
+											{isZh ? '第二条' : 'The second one.'}
+										</div>
+										<div className="shrink-0 w-6 h-6 rounded-full bg-blue-100 dark:bg-blue-900/50 flex items-center justify-center">
+											<Users className="w-3.5 h-3.5 text-blue-600 dark:text-blue-400" />
+										</div>
+									</div>
+									<div className="flex gap-2">
+										<div className="shrink-0 w-6 h-6 rounded-full bg-emerald-100 dark:bg-emerald-900/50 flex items-center justify-center text-emerald-600 dark:text-emerald-400 text-xs font-bold">
+											✓
+										</div>
+										<div className="bg-gray-100 dark:bg-white/10 rounded-2xl rounded-tl-md px-3.5 py-2 text-sm text-gray-700 dark:text-gray-200">
+											{isZh ? '已选择并提交！' : 'Done! Selected and submitted.'}
+										</div>
+									</div>
+								</div>
+								<div className="px-5 pb-5">
+									<div className="flex items-center gap-2.5 mb-1">
+										<MessageSquare className="w-5 h-5 text-blue-500" />
+										<h3 className="font-semibold text-lg text-gray-900 dark:text-white">
+											{isZh ? '人机协同' : 'Human-in-the-Loop'}
+										</h3>
+									</div>
+									<p className="text-sm text-gray-500 dark:text-gray-300 leading-relaxed">
+										{isZh
+											? '内置协作面板，AI 操作前先确认——不是盲目自动化。'
+											: 'Built-in collaborative panel. Agent asks before acting — not blind automation.'}
+									</p>
+								</div>
+							</div>
+						</MagicCard>
+					</BlurFade>
+
+					<BlurFade inView delay={0.2} className="col-span-1 md:col-span-2">
+						<MagicCard
+							className="h-full rounded-2xl"
+							gradientFrom="#f59e0b"
+							gradientTo="#f97316"
+							gradientColor="#f59e0b"
+							gradientOpacity={0.12}
+						>
+							<div className={`flex ${CARD_HEIGHT} flex-col`}>
+								<div className="flex-1 overflow-hidden relative">
+									{LLM_CLOUD.map((item) => (
+										<span
+											key={item.name}
+											className="absolute font-semibold whitespace-nowrap select-none"
+											style={{
+												left: `${item.x}%`,
+												top: `${item.y}%`,
+												fontSize: `${item.size}rem`,
+												color: item.color,
+												opacity: item.opacity,
+												transform: 'translate(-50%, -50%)',
+												textShadow: `0 0 80px ${item.color}99`,
+											}}
+										>
+											{item.name}
+										</span>
+									))}
+								</div>
+								<div className="px-7 pb-5">
+									<div className="flex items-center gap-2.5 mb-1">
+										<Sparkles className="w-5 h-5 text-amber-500" />
+										<h3 className="font-semibold text-lg text-gray-900 dark:text-white">
+											{isZh ? '兼容多种 LLM' : 'Bring Your Own LLMs'}
+										</h3>
+									</div>
+									<p className="text-sm text-gray-500 dark:text-gray-300 leading-relaxed">
+										{isZh
+											? 'OpenAI、Claude、DeepSeek、Qwen 等，或通过 Ollama 完全离线。'
+											: 'OpenAI, Claude, DeepSeek, Qwen, and more — or fully offline via Ollama.'}
+									</p>
+								</div>
+							</div>
+						</MagicCard>
+					</BlurFade>
+				</div>
+			</div>
+		</section>
+	)
+}
diff --git a/packages/website/src/pages/home/HeroSection.tsx b/packages/website/src/pages/home/HeroSection.tsx
new file mode 100644
index 0000000..4d5358a
--- /dev/null
+++ b/packages/website/src/pages/home/HeroSection.tsx
@@ -0,0 +1,423 @@
+import type { PageAgent as PageAgentType } from 'page-agent'
+import { useEffect, useState } from 'react'
+import { Link, useSearchParams } from 'wouter'
+
+import { AnimatedGradientText } from '../../components/ui/animated-gradient-text'
+import { Highlighter } from '../../components/ui/highlighter'
+import { NeonGradientCard } from '../../components/ui/neon-gradient-card'
+import { Particles } from '../../components/ui/particles'
+import {
+	CDN_DEMO_CN_URL,
+	CDN_DEMO_URL,
+	// DEMO_API_KEY,
+	DEMO_BASE_URL,
+	DEMO_MODEL,
+} from '../../constants'
+import { useLanguage } from '../../i18n/context'
+
+let pageAgentModule: Promise<typeof import('page-agent')> | null = null
+
+/**
+ * Get the bookmarklet injection script
+ * @param cdnSource Which CDN mirror to use
+ * @param isZh Whether to use Chinese language
+ */
+function getInjection(cdnSource: 'china' | 'international', isZh?: boolean) {
+	const cdn = cdnSource === 'china' ? CDN_DEMO_CN_URL : CDN_DEMO_URL
+	const locale = isZh ? 'zh-CN' : 'en-US'
+
+	const injection = encodeURI(
+		`javascript:(function(){var s=document.createElement('script');s.src=\`${cdn}?lang=${locale}&t=\${Math.random()}\`;s.setAttribute('crossorigin', true);s.type="text/javascript";s.onload=()=>console.log('PageAgent script loaded!');document.body.appendChild(s);})();`
+	)
+
+	return `
+	<a
+		href=${injection}
+		class="inline-flex items-center text-xs px-3 py-2 bg-blue-500 text-white font-medium rounded-lg hover:shadow-md transform hover:scale-105 transition-all duration-200 cursor-move border-2 border-dashed border-green-300"
+		draggable="true"
+		onclick="return false;"
+		title="Drag me to your bookmarks bar!"
+	>
+		✨PageAgent
+	</a>
+	`
+}
+
+export default function HeroSection() {
+	const { language, isZh } = useLanguage()
+
+	const defaultTask = isZh
+		? '从导航栏中进入文档页，打开"快速开始"相关的文档，帮我总结成 markdown'
+		: 'Goto docs in navigation bar, find Quick-Start section, and summarize in markdown'
+
+	const [task, setTask] = useState(() => defaultTask)
+	const [prevDefaultTask, setPrevDefaultTask] = useState(defaultTask)
+	if (prevDefaultTask !== defaultTask) {
+		setPrevDefaultTask(defaultTask)
+		setTask(defaultTask)
+	}
+
+	const [params] = useSearchParams()
+	const isOther = params.has('try_other')
+
+	const [activeTab, setActiveTab] = useState<'try' | 'other'>(isOther ? 'other' : 'try')
+	const [cdnSource, setCdnSource] = useState<'international' | 'china'>('international')
+
+	const [ready, setReady] = useState(false)
+	useEffect(() => {
+		pageAgentModule ??= import('page-agent')
+		pageAgentModule.then(() => setReady(true))
+	}, [])
+
+	const handleExecute = async () => {
+		if (!task.trim() || !ready || !pageAgentModule) return
+
+		const { PageAgent } = await pageAgentModule
+		const win = window as any
+
+		if (!win.pageAgent || win.pageAgent.disposed) {
+			win.pageAgent = new (PageAgent as typeof PageAgentType)({
+				interactiveBlacklist: [document.getElementById('root')!],
+				language: language,
+
+				instructions: {
+					system: 'You are a helpful assistant on PageAgent website.',
+					getPageInstructions: (url: string) => {
+						return url.includes('page-agent') ? 'This is PageAgent demo page.' : undefined
+					},
+				},
+
+				model:
+					import.meta.env.DEV && import.meta.env.LLM_MODEL_NAME
+						? import.meta.env.LLM_MODEL_NAME
+						: DEMO_MODEL,
+				baseURL:
+					import.meta.env.DEV && import.meta.env.LLM_BASE_URL
+						? import.meta.env.LLM_BASE_URL
+						: DEMO_BASE_URL,
+				apiKey:
+					import.meta.env.DEV && import.meta.env.LLM_API_KEY
+						? import.meta.env.LLM_API_KEY
+						: undefined,
+			})
+		}
+
+		await win.pageAgent.execute(task)
+	}
+
+	return (
+		<section className="relative px-6 pt-18 pb-14 lg:pb-20 lg:pt-24" aria-labelledby="hero-heading">
+			<div className="max-w-7xl mx-auto text-center">
+				{/* Background Pattern + Particles */}
+				<div className="absolute inset-0 opacity-30" aria-hidden="true">
+					<div className="absolute inset-0 bg-linear-to-r from-blue-400/20 to-purple-400/20 rounded-3xl transform rotate-1"></div>
+					<div className="absolute inset-0 bg-linear-to-l from-purple-400/20 to-blue-400/20 rounded-3xl transform -rotate-1"></div>
+				</div>
+				<Particles
+					className="absolute inset-0"
+					quantity={80}
+					staticity={30}
+					ease={80}
+					color="#6366f1"
+				/>
+
+				<div className="relative z-10">
+					<div className="inline-flex items-center px-4 py-2 mb-4 text-sm font-medium bg-white/90 dark:bg-gray-800/90 rounded-full shadow-lg border border-gray-200 dark:border-gray-700">
+						<span
+							className="w-2 h-2 bg-blue-500 rounded-full mr-2 animate-pulse"
+							aria-hidden="true"
+						></span>
+						<AnimatedGradientText colorFrom="#3b82f6" colorTo="#8b5cf6">
+							AI Agent In Your Webpage
+						</AnimatedGradientText>
+					</div>
+
+					<h1
+						id="hero-heading"
+						className="text-5xl lg:text-7xl font-bold mb-10 mt-8 bg-linear-to-r from-blue-600 to-purple-600 bg-clip-text text-transparent pb-1"
+					>
+						{isZh ? (
+							<>
+								<span className="text-6xl lg:text-7xl">你网站里的 AI 操作员</span>
+								<span className="block text-xl lg:text-2xl mt-5 font-medium bg-linear-to-r from-blue-400 to-purple-400 bg-clip-text text-transparent">
+									The AI Operator Living in Your Web Page
+								</span>
+							</>
+						) : (
+							<>
+								The AI Operator
+								<br />
+								Living in Your Web Page
+							</>
+						)}
+					</h1>
+
+					<p className="text-xl lg:text-2xl text-gray-600 dark:text-gray-300 mb-12 max-w-4xl mx-auto leading-relaxed">
+						<Highlighter action="underline" color="#8b5cf6" strokeWidth={2}>
+							<span className="bg-linear-to-r from-blue-500 to-purple-500 bg-clip-text text-transparent font-bold">
+								{isZh ? '🪄一行代码' : '🪄One line of code'}
+							</span>
+						</Highlighter>
+						{isZh
+							? '，让你的网站变身 AI 原生应用。'
+							: ', turns your website into an AI-native app.'}
+						<br />
+						{isZh
+							? '用户/答疑机器人给出文字指示，AI 帮你操作页面。'
+							: 'Users give natural language commands, AI handles the rest.'}
+					</p>
+
+					{/* Try It Now Section - Tab Card */}
+					<div className="mb-12">
+						<div className="max-w-3xl mx-auto">
+							<NeonGradientCard
+								borderSize={2}
+								borderRadius={20}
+								neonColors={{ firstColor: '#ff00aa', secondColor: '#00FFF1' }}
+							>
+								{/* Tab Headers */}
+								<div className="flex border-b border-gray-200 dark:border-gray-700">
+									<button
+										onClick={() => setActiveTab('try')}
+										className={`cursor-pointer flex-1 px-4 py-4 text-lg font-medium transition-colors duration-200 rounded-tl-2xl ${
+											activeTab === 'try'
+												? 'bg-linear-to-r from-blue-50 to-purple-50 dark:from-blue-900/30 dark:to-purple-900/30 text-blue-700 dark:text-blue-300 border-b-2 border-blue-500'
+												: 'text-gray-600 dark:text-gray-400 hover:text-gray-900 dark:hover:text-white hover:bg-gray-50 dark:hover:bg-gray-700'
+										}`}
+									>
+										{isZh ? '🚀 立即尝试' : '🚀 Try It Now'}
+									</button>
+									<button
+										onClick={() => setActiveTab('other')}
+										className={`cursor-pointer flex-1 px-4 py-4 text-lg font-medium transition-colors duration-200 rounded-tr-2xl ${
+											activeTab === 'other'
+												? 'bg-linear-to-r from-green-50 to-blue-50 dark:from-green-900/30 dark:to-blue-900/30 text-green-700 dark:text-green-300 border-b-2 border-green-500'
+												: 'text-gray-600 dark:text-gray-400 hover:text-gray-900 dark:hover:text-white hover:bg-gray-50 dark:hover:bg-gray-700'
+										}`}
+									>
+										{isZh ? '🌐 其他网页尝试' : '🌐 Try on Other Sites'}
+									</button>
+								</div>
+
+								{/* Tab Content */}
+								<div className="p-4">
+									{activeTab === 'try' && (
+										<div className="space-y-4">
+											<div className="relative">
+												<input
+													value={task}
+													onChange={(e) => setTask(e.target.value)}
+													placeholder={
+														isZh
+															? '输入您想要 AI 执行的任务...'
+															: 'Describe what you want AI to do...'
+													}
+													className="w-full px-4 py-3 pr-20 border border-gray-300 dark:border-gray-600 rounded-lg bg-white dark:bg-gray-700 text-gray-900 dark:text-white placeholder-gray-500 dark:placeholder-gray-400 focus:ring-2 focus:ring-blue-500 focus:border-transparent resize-none text-sm mb-0"
+													data-page-agent-not-interactive
+												/>
+												<button
+													onClick={handleExecute}
+													disabled={!ready}
+													className="absolute right-2 top-2 px-5 py-1.5 bg-linear-to-r from-blue-600 to-purple-600 text-white font-medium rounded-md hover:shadow-md transform hover:scale-105 transition-all duration-200 disabled:opacity-50 disabled:cursor-not-allowed disabled:transform-none text-sm"
+													data-page-agent-not-interactive
+												>
+													{ready ? (
+														isZh ? (
+															'执行'
+														) : (
+															'Run'
+														)
+													) : (
+														<span className="animate-pulse">
+															{isZh ? '准备中...' : 'Preparing...'}
+														</span>
+													)}
+												</button>
+											</div>
+											<p className="text-xs text-gray-500 dark:text-gray-400 text-left">
+												{isZh ? (
+													<>
+														使用免费测试 LLM API，点击执行即表示您同意
+														<a
+															href="https://github.com/alibaba/page-agent/blob/main/docs/terms-and-privacy.md#2-testing-api-and-demo-disclaimer--terms-of-use"
+															target="_blank"
+															rel="noopener noreferrer"
+															className="underline"
+														>
+															使用条款
+														</a>
+													</>
+												) : (
+													<>
+														Powered by free testing LLM API. By clicking Run you agree to the{' '}
+														<a
+															href="https://github.com/alibaba/page-agent/blob/main/docs/terms-and-privacy.md#2-testing-api-and-demo-disclaimer--terms-of-use"
+															target="_blank"
+															rel="noopener noreferrer"
+															className="underline"
+														>
+															Terms of Use
+														</a>
+													</>
+												)}
+											</p>
+										</div>
+									)}
+
+									{activeTab === 'other' && (
+										<div className="grid md:grid-cols-2 gap-6">
+											{/* 左侧：操作步骤 */}
+											<div className="space-y-4">
+												<div className="bg-blue-50 dark:bg-gray-700 p-4 rounded-lg">
+													<p className="text-gray-700 dark:text-gray-300 text-sm mb-3">
+														<span className="font-semibold">{isZh ? '步骤 1:' : 'Step 1:'}</span>{' '}
+														{isZh ? '显示收藏夹栏' : 'Show your bookmarks bar'}
+													</p>
+													<div className="flex items-center justify-center gap-2">
+														<kbd className="px-2 py-1 bg-white dark:bg-gray-600 border border-gray-300 dark:border-gray-500 rounded text-xs font-mono">
+															Ctrl + Shift + B
+														</kbd>
+														<span className="text-gray-500 dark:text-gray-400">
+															{isZh ? '或' : 'or'}
+														</span>
+														<kbd className="px-2 py-1 bg-white dark:bg-gray-600 border border-gray-300 dark:border-gray-500 rounded text-xs font-mono">
+															⌘ + Shift + B
+														</kbd>
+													</div>
+												</div>
+
+												<div className="bg-green-50 dark:bg-gray-700 p-4 rounded-lg">
+													<p className="text-gray-700 dark:text-gray-300 text-sm mb-3">
+														<span className="font-semibold">{isZh ? '步骤 2:' : 'Step 2:'}</span>{' '}
+														{isZh ? '拖拽下面按钮到收藏夹栏' : 'Drag this button to your bookmarks'}
+													</p>
+													<div className="flex items-center justify-center gap-3">
+														<select
+															value={cdnSource}
+															onChange={(e) =>
+																setCdnSource(e.target.value as 'international' | 'china')
+															}
+															className="px-2 py-1.5 text-xs border border-gray-300 dark:border-gray-500 rounded bg-white dark:bg-gray-600 text-gray-700 dark:text-gray-200"
+														>
+															<option value="international">jsdelivr CDN</option>
+															<option value="china">npmmirror CDN</option>
+														</select>
+														<div
+															dangerouslySetInnerHTML={{
+																__html: getInjection(cdnSource, isZh),
+															}}
+														></div>
+													</div>
+												</div>
+
+												<div className="bg-purple-50 dark:bg-gray-700 p-4 rounded-lg">
+													<p className="text-gray-700 dark:text-gray-300 text-sm">
+														<span className="font-semibold">{isZh ? '步骤 3:' : 'Step 3:'}</span>{' '}
+														{isZh
+															? '在其他网站点击收藏夹中的按钮即可使用'
+															: 'Click the bookmark on any site to activate'}
+													</p>
+												</div>
+											</div>
+
+											{/* 右侧：注意事项 */}
+											<div className="bg-yellow-50 dark:bg-gray-700 p-4 rounded-lg">
+												<h4 className="font-semibold text-gray-900 dark:text-white mb-3 text-sm">
+													{isZh ? '⚠️ 注意' : '⚠️ Heads Up'}
+												</h4>
+												<ul className="space-y-2 text-sm text-gray-700 dark:text-gray-300">
+													<li className="flex items-start text-left">
+														<span className="w-1.5 h-1.5 bg-yellow-500 rounded-full mt-2 mr-2 shrink-0 "></span>
+														{isZh ? (
+															<span>
+																使用免费测试 LLM API，使用即表示同意
+																<a
+																	href="https://github.com/alibaba/page-agent/blob/main/docs/terms-and-privacy.md#2-testing-api-and-demo-disclaimer--terms-of-use"
+																	target="_blank"
+																	rel="noopener noreferrer"
+																	className="text-yellow-700 dark:text-yellow-300 underline"
+																>
+																	使用条款
+																</a>
+															</span>
+														) : (
+															<span>
+																Uses free testing LLM API. By using you agree to the{' '}
+																<a
+																	href="https://github.com/alibaba/page-agent/blob/main/docs/terms-and-privacy.md#2-testing-api-and-demo-disclaimer--terms-of-use"
+																	target="_blank"
+																	rel="noopener noreferrer"
+																	className="text-yellow-700 dark:text-yellow-300 underline"
+																>
+																	Terms of Use
+																</a>
+															</span>
+														)}
+													</li>
+													<li className="flex items-start text-left">
+														<span className="w-1.5 h-1.5 bg-yellow-500 rounded-full mt-2 mr-2 shrink-0 "></span>
+														{isZh
+															? '数据通过中国大陆服务器处理'
+															: 'Data processed via servers in Mainland China'}
+													</li>
+													<li className="flex items-start text-left">
+														<span className="w-1.5 h-1.5 bg-yellow-500 rounded-full mt-2 mr-2 shrink-0 "></span>
+														{isZh
+															? '部分网站屏蔽了链接嵌入，将无反应'
+															: 'Some sites block script injection (CSP policies)'}
+													</li>
+													<li className="flex items-start text-left">
+														<span className="w-1.5 h-1.5 bg-yellow-500 rounded-full mt-2 mr-2 shrink-0 "></span>
+														{isZh ? '支持单页应用' : 'Works on single-page apps'}
+													</li>
+													<li className="flex items-start text-left">
+														<span className="w-1.5 h-1.5 bg-yellow-500 rounded-full mt-2 mr-2 shrink-0 "></span>
+														{isZh
+															? '仅识别文本，不识别图像，不支持拖拽等复杂交互'
+															: 'Text-only understanding—no image recognition or drag-and-drop'}
+													</li>
+													<li className="flex items-start text-left">
+														<span className="w-1.5 h-1.5 bg-yellow-500 rounded-full mt-2 mr-2 shrink-0 "></span>
+														{isZh ? '详细使用限制参照' : 'Full limitations in'}
+														<Link
+															href="/docs/introduction/limitations"
+															className="text-blue-600 dark:text-blue-400 hover:underline pl-1"
+														>
+															{isZh ? '《文档》' : 'Docs'}
+														</Link>
+													</li>
+												</ul>
+											</div>
+										</div>
+									)}
+								</div>
+							</NeonGradientCard>
+						</div>
+					</div>
+
+					<ul
+						className="flex flex-wrap justify-center gap-6 text-sm text-gray-500 dark:text-gray-400"
+						role="list"
+					>
+						<li className="flex items-center">
+							<span className="w-2 h-2 bg-green-500 rounded-full mr-2" aria-hidden="true"></span>
+							{isZh ? '纯前端方案' : 'Pure Front-end Solution'}
+						</li>
+						<li className="flex items-center">
+							<span className="w-2 h-2 bg-green-500 rounded-full mr-2" aria-hidden="true"></span>
+							{isZh ? '支持私有模型' : 'Your Own Models'}
+						</li>
+						<li className="flex items-center">
+							<span className="w-2 h-2 bg-green-500 rounded-full mr-2" aria-hidden="true"></span>
+							{isZh ? '无痛脱敏' : 'Built-in Privacy'}
+						</li>
+						<li className="flex items-center">
+							<span className="w-2 h-2 bg-green-500 rounded-full mr-2" aria-hidden="true"></span>
+							{isZh ? 'MIT 开源' : 'MIT Open Source'}
+						</li>
+					</ul>
+				</div>
+			</div>
+		</section>
+	)
+}
diff --git a/packages/website/src/pages/home/OneMoreThingSection.tsx b/packages/website/src/pages/home/OneMoreThingSection.tsx
new file mode 100644
index 0000000..1c50a93
--- /dev/null
+++ b/packages/website/src/pages/home/OneMoreThingSection.tsx
@@ -0,0 +1,114 @@
+import { ExternalLink } from 'lucide-react'
+import { siGooglechrome } from 'simple-icons'
+import { Link } from 'wouter'
+
+import { BlurFade } from '../../components/ui/blur-fade'
+import { MagicCard } from '../../components/ui/magic-card'
+import { useLanguage } from '../../i18n/context'
+
+export default function OneMoreThingSection() {
+	const { isZh } = useLanguage()
+
+	return (
+		<section className="px-6 py-14" aria-labelledby="one-more-thing-heading">
+			<div className="max-w-4xl mx-auto text-center">
+				<BlurFade inView>
+					<h2
+						id="one-more-thing-heading"
+						className="text-4xl lg:text-5xl font-bold mb-6 bg-linear-to-r from-blue-600 to-purple-600 bg-clip-text text-transparent"
+					>
+						One More Thing
+					</h2>
+					<p className="text-xl text-gray-600 dark:text-gray-300 mb-4 max-w-2xl mx-auto">
+						{isZh
+							? '想要多页面控制？试试可选的浏览器扩展。'
+							: 'Need multi-page control? Try the optional browser extension.'}
+					</p>
+					<p className="text-sm text-gray-500 dark:text-gray-400 mb-12 max-w-2xl mx-auto">
+						{'* '}
+						{isZh
+							? 'PageAgent.js 本身无需任何扩展即可工作，扩展是额外的能力增强。'
+							: 'PageAgent.js works without any extension — this is a power-up, not a dependency.'}
+					</p>
+				</BlurFade>
+
+				<div className="flex flex-col sm:flex-row items-center justify-center gap-4 mb-12">
+					<a
+						href="https://chromewebstore.google.com/detail/page-agent-ext/akldabonmimlicnjlflnapfeklbfemhj"
+						target="_blank"
+						rel="noopener noreferrer"
+						className="group inline-flex items-center gap-3 px-8 py-4 bg-linear-to-r from-blue-600 to-blue-700 hover:from-blue-700 hover:to-blue-800 text-white font-medium rounded-2xl shadow-lg hover:shadow-xl transition-all duration-300 hover:scale-105"
+					>
+						<img
+							src="https://page-agent.github.io/assets/third-party/chrome-web-store-192.svg"
+							alt="Chrome Web Store"
+							className="w-7 h-7"
+						/>
+						<span>{isZh ? '从 Chrome 应用商店安装' : 'Install from Chrome Web Store'}</span>
+						<ExternalLink className="w-4 h-4 opacity-50 group-hover:opacity-100 transition-opacity" />
+					</a>
+					<Link
+						href="/docs/features/chrome-extension"
+						className="inline-flex items-center gap-3 px-8 py-4 bg-gray-100 dark:bg-gray-700 hover:bg-gray-200 dark:hover:bg-gray-600 text-gray-900 dark:text-white font-medium rounded-2xl transition-all duration-300 hover:scale-105"
+					>
+						<svg className="w-5 h-5" viewBox="0 0 24 24" aria-hidden="true">
+							<path d={siGooglechrome.path} fill="currentColor" />
+						</svg>
+						<span>{isZh ? '查看文档' : 'Read the Docs'}</span>
+					</Link>
+				</div>
+
+				<div className="mb-10 rounded-2xl border border-blue-200/70 dark:border-blue-800/70 bg-linear-to-r from-blue-50 to-white dark:from-blue-950/30 dark:to-gray-900 px-5 py-4 max-w-3xl mx-auto text-left sm:text-center">
+					<p className="text-sm text-gray-700 dark:text-gray-300 leading-7">
+						{isZh
+							? '从 Claude Desktop、Copilot 或其他本地 Agent 直接发起浏览器任务？'
+							: 'Using Claude Desktop, Copilot, or another local agent? Connect it to the extension with the MCP server.'}
+					</p>
+					<p>
+						<Link
+							href="/docs/features/mcp-server"
+							className="font-medium text-blue-700 dark:text-blue-300 underline underline-offset-4"
+						>
+							{isZh ? '查看 MCP 文档' : 'Read the MCP docs'}
+						</Link>
+					</p>
+				</div>
+
+				<div className="grid sm:grid-cols-3 gap-5 text-left max-w-3xl mx-auto">
+					{[
+						{
+							title: isZh ? '多页面任务' : 'Multi-Page Tasks',
+							desc: isZh
+								? '跨多个页面和标签页连续执行任务，不再受限于单页上下文'
+								: 'Run tasks across multiple pages and tabs without being limited to a single page context',
+						},
+						{
+							title: isZh ? '从页面发起控制' : 'Control from a WebPage',
+							desc: isZh
+								? '在页面 JS 中发起任务，驱动整个浏览器完成跨标签操作'
+								: 'Trigger tasks from in-page JS to drive the entire browser across tabs',
+						},
+						{
+							title: isZh ? '外部发起任务' : 'External Caller',
+							desc: isZh
+								? '页面 JS、本地 Agent 或云端 Agent 均可通过扩展发起任务'
+								: 'Local agents and cloud agents can control user browser through the extension',
+						},
+					].map((item) => (
+						<MagicCard
+							key={item.title}
+							className="rounded-xl"
+							gradientColor="#8b5cf620"
+							gradientOpacity={0.15}
+						>
+							<div className="p-5">
+								<h3 className="font-semibold text-gray-900 dark:text-white mb-1">{item.title}</h3>
+								<p className="text-sm text-gray-600 dark:text-gray-300">{item.desc}</p>
+							</div>
+						</MagicCard>
+					))}
+				</div>
+			</div>
+		</section>
+	)
+}
diff --git a/packages/website/src/pages/home/ScenariosSection.tsx b/packages/website/src/pages/home/ScenariosSection.tsx
new file mode 100644
index 0000000..fdb0af9
--- /dev/null
+++ b/packages/website/src/pages/home/ScenariosSection.tsx
@@ -0,0 +1,165 @@
+import { Bot, Users, Zap } from 'lucide-react'
+
+import { BlurFade } from '../../components/ui/blur-fade'
+import { SparklesText } from '../../components/ui/sparkles-text'
+import { useLanguage } from '../../i18n/context'
+
+export default function ScenariosSection() {
+	const { isZh } = useLanguage()
+
+	return (
+		<section
+			className="px-6 py-16 bg-linear-to-b from-blue-100 to-purple-100 dark:from-blue-950/40 dark:to-gray-800"
+			aria-labelledby="scenarios-heading"
+		>
+			<div className="max-w-6xl mx-auto">
+				<BlurFade inView>
+					<div className="text-center mb-12">
+						<SparklesText
+							className="text-4xl lg:text-5xl mb-6"
+							colors={{ first: '#3b82f6', second: '#8b5cf6' }}
+						>
+							{isZh ? '应用场景' : 'Built For'}
+						</SparklesText>
+					</div>
+				</BlurFade>
+
+				<div className="grid grid-cols-1 md:grid-cols-3 gap-6">
+					{/* SaaS AI Copilot */}
+					<BlurFade inView delay={0.05}>
+						<div className="group relative overflow-hidden rounded-2xl bg-linear-to-b from-blue-50 to-white dark:from-blue-950/40 dark:to-gray-800 border border-blue-200/80 dark:border-blue-800/50 shadow-sm hover:shadow-xl hover:-translate-y-1 transition-all duration-500">
+							<div className="p-6 pb-4">
+								<div className="rounded-xl bg-gray-950 p-4 font-mono text-xs leading-6 text-gray-300 overflow-hidden shadow-inner">
+									<div>
+										<span className="text-purple-400">import</span> {'{ PageAgent }'}{' '}
+										<span className="text-purple-400">from</span>{' '}
+										<span className="text-emerald-400">'page-agent'</span>
+									</div>
+									<div className="mt-2">
+										<span className="text-purple-400">const</span>{' '}
+										<span className="text-blue-300">copilot</span> ={' '}
+										<span className="text-purple-400">new</span>{' '}
+										<span className="text-yellow-300">PageAgent</span>
+										{'({'}
+									</div>
+									<div className="pl-4">
+										<span className="text-blue-300">model</span>:{' '}
+										<span className="text-emerald-400">'gpt-5.1'</span>,
+									</div>
+									<div className="pl-4">
+										<span className="text-blue-300">apiKey</span>:{' '}
+										<span className="text-emerald-400">process.env.KEY</span>,
+									</div>
+									<div>{'})'}</div>
+								</div>
+							</div>
+							<div className="p-6 pt-2">
+								<div className="flex items-center gap-2 mb-2">
+									<Bot className="w-5 h-5 text-blue-500" />
+									<h3 className="font-semibold text-lg text-gray-900 dark:text-white">
+										{isZh ? 'SaaS AI 副驾驶' : 'SaaS AI Copilot'}
+									</h3>
+								</div>
+								<p className="text-sm text-gray-600 dark:text-gray-300 leading-relaxed">
+									{isZh
+										? '几小时内为你的产品加上 AI 副驾驶，不需要重写后端。'
+										: 'Ship an AI copilot in your product in hours, not months. No backend rewrite needed.'}
+								</p>
+							</div>
+						</div>
+					</BlurFade>
+
+					{/* Smart Form Filling */}
+					<BlurFade inView delay={0.1}>
+						<div className="group relative overflow-hidden rounded-2xl bg-linear-to-b from-amber-50 to-white dark:from-amber-950/40 dark:to-gray-800 border border-amber-200/80 dark:border-amber-800/50 shadow-sm hover:shadow-xl hover:-translate-y-1 transition-all duration-500">
+							<div className="p-6 pb-4">
+								<div className="rounded-xl bg-white dark:bg-gray-900 border border-gray-200 dark:border-gray-700 p-4 shadow-inner space-y-2.5">
+									<div className="flex items-center gap-2 text-xs text-gray-500 dark:text-gray-400 bg-amber-50 dark:bg-amber-900/30 rounded-lg px-3 py-2 border border-amber-200/50 dark:border-amber-700/40">
+										<span>🪄</span>
+										<span className="italic">
+											{isZh
+												? '"填写上周五出差的报销单"'
+												: '"Fill the expense report for Friday\'s trip"'}
+										</span>
+									</div>
+									{[
+										{ label: isZh ? '姓名' : 'Name', value: 'John Smith' },
+										{ label: isZh ? '金额' : 'Amount', value: '$342.50' },
+										{ label: isZh ? '类目' : 'Category', value: 'Travel' },
+									].map((field) => (
+										<div key={field.label} className="flex items-center gap-2">
+											<span className="text-xs text-gray-400 dark:text-gray-500 w-12 shrink-0">
+												{field.label}
+											</span>
+											<div className="flex-1 h-7 bg-gray-50 dark:bg-gray-800 rounded border border-gray-200 dark:border-gray-600 px-2 flex items-center text-xs text-gray-600 dark:text-gray-300">
+												{field.value}
+											</div>
+											<span className="text-emerald-500 text-xs">✓</span>
+										</div>
+									))}
+								</div>
+							</div>
+							<div className="p-6 pt-2">
+								<div className="flex items-center gap-2 mb-2">
+									<Zap className="w-5 h-5 text-amber-500" />
+									<h3 className="font-semibold text-lg text-gray-900 dark:text-white">
+										{isZh ? '智能表单填写' : 'Smart Form Filling'}
+									</h3>
+								</div>
+								<p className="text-sm text-gray-600 dark:text-gray-300 leading-relaxed">
+									{isZh
+										? '把 20 次点击变成一句话。ERP、CRM、管理后台的最佳拍档。'
+										: 'Turn 20-click workflows into one sentence. Perfect for ERP, CRM, and admin systems.'}
+								</p>
+							</div>
+						</div>
+					</BlurFade>
+
+					{/* Accessibility */}
+					<BlurFade inView delay={0.15}>
+						<div className="group relative overflow-hidden rounded-2xl bg-linear-to-b from-purple-50 to-white dark:from-purple-950/40 dark:to-gray-800 border border-purple-200/80 dark:border-purple-800/50 shadow-sm hover:shadow-xl hover:-translate-y-1 transition-all duration-500">
+							<div className="p-6 pb-4 flex flex-col items-center justify-center">
+								<div className="w-full rounded-xl bg-purple-50 dark:bg-purple-900/30 p-5 space-y-3">
+									<div className="flex items-center gap-3">
+										<div className="w-8 h-8 rounded-full bg-purple-500/10 dark:bg-purple-500/20 flex items-center justify-center text-base">
+											🎤
+										</div>
+										<div className="text-sm text-purple-700 dark:text-purple-300 italic">
+											{isZh ? '"点击提交按钮"' : '"Click the submit button"'}
+										</div>
+									</div>
+									<div className="flex items-center gap-3 pl-11">
+										<div className="flex items-center gap-1.5">
+											<div className="w-1.5 h-1.5 bg-purple-400 rounded-full animate-pulse"></div>
+											<div className="w-1.5 h-1.5 bg-purple-400 rounded-full animate-pulse [animation-delay:0.2s]"></div>
+											<div className="w-1.5 h-1.5 bg-purple-400 rounded-full animate-pulse [animation-delay:0.4s]"></div>
+										</div>
+										<span className="text-xs text-purple-500 dark:text-purple-400">
+											{isZh ? 'AI 正在执行...' : 'AI executing...'}
+										</span>
+									</div>
+									<div className="flex items-center gap-3 pl-11 text-sm text-emerald-600 dark:text-emerald-400">
+										<span>✓</span> {isZh ? '按钮已点击' : 'Button clicked'}
+									</div>
+								</div>
+							</div>
+							<div className="p-6 pt-2">
+								<div className="flex items-center gap-2 mb-2">
+									<Users className="w-5 h-5 text-purple-500" />
+									<h3 className="font-semibold text-lg text-gray-900 dark:text-white">
+										{isZh ? '无障碍增强' : 'Accessibility'}
+									</h3>
+								</div>
+								<p className="text-sm text-gray-600 dark:text-gray-300 leading-relaxed">
+									{isZh
+										? '用自然语言让任何网页无障碍。语音指令、屏幕阅读器，零门槛。'
+										: 'Make any web app accessible through natural language. Voice, screen readers, zero barrier.'}
+								</p>
+							</div>
+						</div>
+					</BlurFade>
+				</div>
+			</div>
+		</section>
+	)
+}
diff --git a/packages/website/src/pages/home/index.tsx b/packages/website/src/pages/home/index.tsx
new file mode 100644
index 0000000..9781e6b
--- /dev/null
+++ b/packages/website/src/pages/home/index.tsx
@@ -0,0 +1,31 @@
+import { Suspense, lazy } from 'react'
+
+import { useDocumentTitle } from '@/lib/useDocumentTitle'
+
+import HeroSection from './HeroSection'
+
+const FeaturesSection = lazy(() => import('./FeaturesSection'))
+const ScenariosSection = lazy(() => import('./ScenariosSection'))
+const OneMoreThingSection = lazy(() => import('./OneMoreThingSection'))
+
+export default function HomePage() {
+	useDocumentTitle()
+
+	return (
+		<>
+			<HeroSection />
+			<Suspense
+				fallback={
+					<div className="flex items-center justify-center gap-3 py-20 text-gray-400">
+						<div className="w-4 h-4 border-2 border-blue-500 border-t-transparent rounded-full animate-spin" />
+						Loading...
+					</div>
+				}
+			>
+				<FeaturesSection />
+				<ScenariosSection />
+				<OneMoreThingSection />
+			</Suspense>
+		</>
+	)
+}
diff --git a/packages/website/src/router.tsx b/packages/website/src/router.tsx
new file mode 100644
index 0000000..2571bec
--- /dev/null
+++ b/packages/website/src/router.tsx
@@ -0,0 +1,72 @@
+import { Suspense, lazy, useEffect, useLayoutEffect } from 'react'
+import { Route, Switch, useLocation } from 'wouter'
+
+import Footer from './components/Footer'
+import Header from './components/Header'
+import HomePage from './pages/home'
+
+const docsImport = () => import('./pages/docs')
+const DocsPages = lazy(docsImport)
+
+function ScrollToTop() {
+	const [pathname] = useLocation()
+	useLayoutEffect(() => {
+		window.scrollTo(0, 0)
+	}, [pathname])
+	return null
+}
+
+export default function Router() {
+	useEffect(() => {
+		if ('requestIdleCallback' in globalThis) {
+			const id = requestIdleCallback(() => docsImport())
+			return () => cancelIdleCallback(id)
+		}
+		const id = setTimeout(() => docsImport(), 1)
+		return () => clearTimeout(id)
+	}, [])
+
+	return (
+		<div className="flex min-h-screen flex-col">
+			<Header />
+			<Suspense>
+				<ScrollToTop />
+				<Switch>
+					<Route path="/">
+						<main
+							id="main-content"
+							className="flex-1 bg-linear-to-br from-blue-50 to-purple-50 dark:from-gray-900 dark:to-gray-800"
+						>
+							<HomePage />
+						</main>
+					</Route>
+
+					<Route path="/docs" nest>
+						<div className="flex-1 bg-white dark:bg-gray-900">
+							<Suspense
+								fallback={
+									<div className="flex items-center justify-center gap-3 py-20 text-gray-400">
+										<div className="w-4 h-4 border-2 border-blue-500 border-t-transparent rounded-full animate-spin" />
+										Loading...
+									</div>
+								}
+							>
+								<DocsPages />
+							</Suspense>
+						</div>
+					</Route>
+
+					<Route>
+						<div className="flex-1 bg-white dark:bg-gray-900 flex items-center justify-center">
+							<div className="text-center">
+								<h1 className="text-4xl font-bold mb-4 text-gray-900 dark:text-white">404</h1>
+								<p className="text-xl text-gray-600 dark:text-gray-300">Page not found</p>
+							</div>
+						</div>
+					</Route>
+				</Switch>
+			</Suspense>
+			<Footer />
+		</div>
+	)
+}
diff --git a/packages/website/tailwind.config.js b/packages/website/tailwind.config.js
new file mode 100644
index 0000000..057000f
--- /dev/null
+++ b/packages/website/tailwind.config.js
@@ -0,0 +1,3 @@
+export default {
+	important: '#root',
+}
diff --git a/packages/website/tsconfig.json b/packages/website/tsconfig.json
new file mode 100644
index 0000000..b9fbd7e
--- /dev/null
+++ b/packages/website/tsconfig.json
@@ -0,0 +1,11 @@
+{
+    "extends": "../../tsconfig.base.json",
+    "compilerOptions": {
+        "tsBuildInfoFile": "./node_modules/.tmp/tsconfig.tsbuildinfo",
+        "paths": {
+            "@/*": ["./src/*"]
+        }
+    },
+    "include": ["src/**/*.ts", "src/**/*.tsx"],
+    "exclude": ["dist", "node_modules"]
+}
diff --git a/packages/website/vite.config.js b/packages/website/vite.config.js
new file mode 100644
index 0000000..09abfb7
--- /dev/null
+++ b/packages/website/vite.config.js
@@ -0,0 +1,106 @@
+import tailwindcss from '@tailwindcss/vite'
+import react from '@vitejs/plugin-react'
+import { config as dotenvConfig } from 'dotenv'
+import { copyFileSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import process from 'node:process'
+import { dirname, join, resolve } from 'path'
+import { fileURLToPath } from 'url'
+import { defineConfig } from 'vite'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+const pageAgentPkg = JSON.parse(
+	readFileSync(resolve(__dirname, '../page-agent/package.json'), 'utf-8')
+)
+
+// Load .env from repo root
+dotenvConfig({ path: resolve(__dirname, '../../.env'), quiet: true })
+
+// All SPA routes that need index.html copies for direct access on static hosts
+const SPA_ROUTES = [
+	'docs',
+	'docs/introduction/overview',
+	'docs/introduction/quick-start',
+	'docs/introduction/limitations',
+	'docs/introduction/troubleshooting',
+	'docs/features/custom-tools',
+	'docs/features/data-masking',
+	'docs/features/custom-instructions',
+	'docs/features/models',
+	'docs/features/local-llms',
+	'docs/features/chrome-extension',
+	'docs/features/mcp-server',
+	'docs/features/third-party-agent',
+	'docs/advanced/page-agent',
+	'docs/advanced/page-agent-core',
+	'docs/advanced/page-controller',
+	'docs/advanced/custom-ui',
+	'docs/advanced/security-permissions',
+]
+
+const SITE_URL = 'https://alibaba.github.io/page-agent'
+
+function spaRoutes() {
+	return {
+		name: 'spa-routes',
+		closeBundle() {
+			const dist = resolve(__dirname, 'dist')
+			const src = join(dist, 'index.html')
+			for (const route of SPA_ROUTES) {
+				const dir = join(dist, route)
+				mkdirSync(dir, { recursive: true })
+				copyFileSync(src, join(dir, 'index.html'))
+			}
+			console.log(`  ✓ Copied index.html to ${SPA_ROUTES.length} SPA routes`)
+
+			const today = new Date().toISOString().split('T')[0]
+			const urls = ['', ...SPA_ROUTES]
+				.map(
+					(route) =>
+						`  <url>\n    <loc>${SITE_URL}/${route}</loc>\n    <lastmod>${today}</lastmod>\n  </url>`
+				)
+				.join('\n')
+			writeFileSync(
+				join(dist, 'sitemap.xml'),
+				`<?xml version="1.0" encoding="UTF-8"?>\n<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">\n${urls}\n</urlset>\n`
+			)
+			console.log(`  ✓ Generated sitemap.xml with ${SPA_ROUTES.length + 1} URLs`)
+		},
+	}
+}
+
+// Website Config (React Documentation Site)
+export default defineConfig(({ mode }) => ({
+	base: '/page-agent/',
+	clearScreen: false,
+	plugins: [react(), tailwindcss(), spaRoutes()],
+	build: {
+		chunkSizeWarningLimit: 2000,
+		cssCodeSplit: true,
+		rollupOptions: {
+			onwarn: function (message, handler) {
+				if (message.code === 'EVAL') return
+				handler(message)
+			},
+			output: {
+				manualChunks(id) {
+					if (/[\\/]node_modules[\\/](react|react-dom|wouter)([\\/]|$)/.test(id)) {
+						return 'vendor'
+					}
+				},
+			},
+		},
+	},
+	resolve: {
+		alias: {
+			'@': resolve(__dirname, 'src'),
+		},
+	},
+	define: {
+		...(mode === 'development' && {
+			'import.meta.env.LLM_MODEL_NAME': JSON.stringify(process.env.LLM_MODEL_NAME),
+			'import.meta.env.LLM_API_KEY': JSON.stringify(process.env.LLM_API_KEY),
+			'import.meta.env.LLM_BASE_URL': JSON.stringify(process.env.LLM_BASE_URL),
+		}),
+		'import.meta.env.VERSION': JSON.stringify(pageAgentPkg.version),
+	},
+}))
diff --git a/scripts/build-libs.js b/scripts/build-libs.js
new file mode 100644
index 0000000..4ad78fb
--- /dev/null
+++ b/scripts/build-libs.js
@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+/**
+ * Equivalent to: npm run build --workspaces --if-present
+ *
+ * Reads the workspace list from root package.json, filters to those with a
+ * "build" script, and runs them all concurrently via parallelTask.
+ */
+import { readFileSync } from 'fs'
+import { dirname, join } from 'path'
+import { fileURLToPath } from 'url'
+
+import { parallelTask } from './parallel-task.js'
+
+const rootDir = join(dirname(fileURLToPath(import.meta.url)), '..')
+const rootPkg = JSON.parse(readFileSync(join(rootDir, 'package.json'), 'utf-8'))
+
+const tasks = rootPkg.workspaces
+	.map((ws) => {
+		const dir = join(rootDir, ws)
+		const pkg = JSON.parse(readFileSync(join(dir, 'package.json'), 'utf-8'))
+		return pkg.scripts?.build ? { label: pkg.name, command: 'npm run build', cwd: dir } : null
+	})
+	.filter(Boolean)
+
+await parallelTask(tasks, { timeoutMs: 120_000 })
diff --git a/scripts/build.js b/scripts/build.js
new file mode 100644
index 0000000..81e26d3
--- /dev/null
+++ b/scripts/build.js
@@ -0,0 +1,45 @@
+#!/usr/bin/env node
+/**
+ * Full build pipeline. Equivalent to:
+ *   npm run cleanup && npm run build --workspaces --if-present
+ *                    && npm run build:website -w @page-agent/website
+ *                    && npm run zip -w @page-agent/ext
+ *
+ * 1. cleanup
+ * 2. build everything in parallel (libs + website + extension)
+ */
+import chalk from 'chalk'
+import { execSync } from 'child_process'
+import { readFileSync } from 'fs'
+import { dirname, join } from 'path'
+import { fileURLToPath } from 'url'
+
+import { parallelTask } from './parallel-task.js'
+
+const rootDir = join(dirname(fileURLToPath(import.meta.url)), '..')
+const rootPkg = JSON.parse(readFileSync(join(rootDir, 'package.json'), 'utf-8'))
+
+// Step 1: cleanup
+console.log(chalk.bgBlue.white.bold(' ▸ cleanup '))
+execSync('npm run cleanup', { cwd: rootDir, stdio: 'inherit' })
+
+// Step 2: build all in parallel
+console.log(chalk.bgBlue.white.bold(' ▸ build '))
+const tasks = rootPkg.workspaces
+	.map((ws) => {
+		const dir = join(rootDir, ws)
+		const pkg = JSON.parse(readFileSync(join(dir, 'package.json'), 'utf-8'))
+		return pkg.scripts?.build ? { label: pkg.name, command: 'npm run build', cwd: dir } : null
+	})
+	.filter(Boolean)
+
+tasks.push(
+	{
+		label: '@page-agent/website',
+		command: 'npm run build:website',
+		cwd: join(rootDir, 'packages/website'),
+	},
+	{ label: '@page-agent/ext', command: 'npm run zip', cwd: join(rootDir, 'packages/extension') }
+)
+
+await parallelTask(tasks, { timeoutMs: 120_000 })
diff --git a/scripts/ci.js b/scripts/ci.js
new file mode 100644
index 0000000..be88288
--- /dev/null
+++ b/scripts/ci.js
@@ -0,0 +1,56 @@
+#!/usr/bin/env node
+/**
+ * CI check script. Run locally before commit or in GitHub Actions.
+ *
+ * Usage:
+ *   node scripts/ci.js            # run all checks
+ *   node scripts/ci.js --no-build # skip build step
+ */
+import chalk from 'chalk'
+import { execSync } from 'child_process'
+
+import { parallelTask } from './parallel-task.js'
+
+const args = new Set(process.argv.slice(2))
+const skipBuild = args.has('--no-build')
+
+function run(label, command) {
+	console.log(chalk.bgBlue.white.bold(` ▸ ${label} `))
+	execSync(command, { stdio: 'inherit' })
+}
+
+function isMainBranch() {
+	if (process.env.GITHUB_REF) return process.env.GITHUB_REF === 'refs/heads/main'
+	try {
+		return execSync('git rev-parse --abbrev-ref HEAD', { encoding: 'utf-8' }).trim() === 'main'
+	} catch {
+		return true
+	}
+}
+
+// 1. Commitlint — skip on main
+if (isMainBranch()) {
+	console.log(chalk.dim(' ▸ commitlint (skipped on main)'))
+} else {
+	const from = execSync('git merge-base origin/main HEAD', { encoding: 'utf-8' }).trim()
+	run('commitlint', `npx commitlint --from ${from} --to HEAD`)
+}
+
+// 2. Lint + Format + Typecheck + Test in parallel
+console.log(chalk.bgBlue.white.bold(' ▸ lint + format + typecheck + test '))
+await parallelTask(
+	[
+		{ label: 'lint', command: 'npm run lint' },
+		{ label: 'format', command: 'npx prettier --check .' },
+		{ label: 'typecheck', command: 'npm run typecheck' },
+		{ label: 'test', command: 'npm test' },
+	],
+	{ timeoutMs: 120_000 }
+)
+
+// 3. Build
+if (skipBuild) {
+	console.log(chalk.dim(' ▸ build (skipped)'))
+} else {
+	run('build', 'npm run build')
+}
diff --git a/scripts/parallel-task.js b/scripts/parallel-task.js
new file mode 100644
index 0000000..2cb3248
--- /dev/null
+++ b/scripts/parallel-task.js
@@ -0,0 +1,115 @@
+import chalk from 'chalk'
+import { spawn } from 'child_process'
+
+/**
+ * Run multiple shell commands in parallel with progress reporting.
+ *
+ * @param {{ label: string, command: string, cwd?: string }[]} tasks
+ * @param {{ timeoutMs?: number }} options - Default timeout 30s per task
+ * @returns {Promise<void>} Rejects (process.exit) if any task fails
+ */
+export async function parallelTask(tasks, options = {}) {
+	const { timeoutMs = 30_000 } = options
+	const total = tasks.length
+
+	const bgColors = [
+		chalk.bgCyan,
+		chalk.bgMagenta,
+		chalk.bgBlue,
+		chalk.bgYellow,
+		chalk.bgGreenBright,
+	]
+	const fgOnBg = [chalk.black, chalk.white, chalk.white, chalk.black, chalk.black]
+
+	let done = 0
+	let failed = 0
+
+	const spinner = ['◐', '◓', '◑', '◒']
+	let tick = 0
+
+	const printProgress = () => {
+		const running = total - done - failed
+		const s = spinner[tick++ % spinner.length]
+		const status = failed
+			? `${running} running, ${done} done, ${chalk.bgRed.white.bold(` ${failed} failed `)}`
+			: `${running} running, ${done} done`
+		process.stderr.write(`\r${chalk.bgCyan.black.bold(` ${s} ${done}/${total} `)} ${status}  `)
+	}
+
+	const timer = setInterval(printProgress, 1000)
+	printProgress()
+
+	/** @type {{ label: string, output: string, exitCode: number | null, timedOut: boolean }[]} */
+	const results = await Promise.all(
+		tasks.map(
+			(task) =>
+				new Promise((resolve) => {
+					const chunks = /** @type {Buffer[]} */ ([])
+
+					const child = spawn('sh', ['-c', task.command], {
+						cwd: task.cwd,
+						env: { ...process.env, FORCE_COLOR: '1', NO_COLOR: '' },
+						stdio: ['ignore', 'pipe', 'pipe'],
+					})
+
+					child.stdout.on('data', (d) => chunks.push(d))
+					child.stderr.on('data', (d) => chunks.push(d))
+
+					const timeout = setTimeout(() => {
+						child.kill('SIGTERM')
+					}, timeoutMs)
+
+					child.on('close', (code, signal) => {
+						clearTimeout(timeout)
+						const timedOut = signal === 'SIGTERM'
+						const exitCode = timedOut ? 1 : code
+
+						if (exitCode === 0) done++
+						else failed++
+
+						resolve({
+							label: task.label,
+							output: Buffer.concat(chunks).toString(),
+							exitCode,
+							timedOut,
+						})
+					})
+				})
+		)
+	)
+
+	clearInterval(timer)
+	process.stderr.write('\r\x1b[K')
+
+	const failedTasks = /** @type {typeof results} */ ([])
+
+	for (let i = 0; i < results.length; i++) {
+		const r = results[i]
+		if (r.exitCode !== 0) {
+			failedTasks.push(r)
+			continue
+		}
+		const bg = bgColors[i % bgColors.length]
+		const fg = fgOnBg[i % fgOnBg.length]
+		const banner = bg(fg.bold(` ✔ ${r.label} `))
+		console.log(`\n${banner}`)
+		if (r.output.trim()) process.stdout.write(r.output)
+	}
+
+	if (failedTasks.length) {
+		for (const r of failedTasks) {
+			const banner = chalk.bgRed(
+				chalk.white.bold(` ✘ ${r.label} ${r.timedOut ? '· timed out' : '· failed'} `)
+			)
+			console.log(`\n${banner}`)
+			if (r.output.trim()) process.stdout.write(r.output)
+		}
+		const summary = failedTasks.map((t) => t.label).join(', ')
+		console.error(
+			`\n${chalk.bgRed.white.bold(` ✘ ${failedTasks.length}/${total} failed: ${summary} `)}`
+		)
+		process.exit(1)
+	}
+
+	console.log(`\n${chalk.bgGreen.black.bold(` ✔ All ${total} tasks completed `)}`)
+}
diff --git a/scripts/post-publish.js b/scripts/post-publish.js
new file mode 100644
index 0000000..e429700
--- /dev/null
+++ b/scripts/post-publish.js
@@ -0,0 +1,30 @@
+#!/usr/bin/env node
+/**
+ * Restore package.json from the backup created by pre-publish.js,
+ * then clean up temporary files (backup, LICENSE, README.md).
+ *
+ * Usage: node ../../scripts/post-publish.js   (from a package dir)
+ */
+import { existsSync, readFileSync, renameSync, rmSync } from 'fs'
+import { join } from 'path'
+
+const pkgPath = join(process.cwd(), 'package.json')
+const bakPath = pkgPath + '.bak'
+
+if (!existsSync(bakPath)) {
+	console.log('  No backup found, nothing to restore.')
+	process.exit(0)
+}
+
+const name = JSON.parse(readFileSync(pkgPath, 'utf-8')).name
+
+renameSync(bakPath, pkgPath)
+console.log('  ✓ package.json restored from backup')
+
+rmSync(join(process.cwd(), 'LICENSE'), { force: true })
+console.log('  ✓ LICENSE removed')
+
+if (name === 'page-agent') {
+	rmSync(join(process.cwd(), 'README.md'), { force: true })
+	console.log('  ✓ README.md removed')
+}
diff --git a/scripts/pre-publish.js b/scripts/pre-publish.js
new file mode 100644
index 0000000..44dc929
--- /dev/null
+++ b/scripts/pre-publish.js
@@ -0,0 +1,42 @@
+#!/usr/bin/env node
+/**
+ * Backup package.json, then rewrite it for publish:
+ *   - Promote `publishConfig` fields to top level
+ *   - Remove `publishConfig` (npm doesn't need the wrapper)
+ *   - Copy LICENSE (and README.md for the main package)
+ *
+ * Usage: node ../../scripts/pre-publish.js   (from a package dir)
+ */
+import { copyFileSync, readFileSync, writeFileSync } from 'fs'
+import { join } from 'path'
+
+const pkgPath = join(process.cwd(), 'package.json')
+const raw = readFileSync(pkgPath, 'utf-8')
+const pkg = JSON.parse(raw)
+
+const publishConfig = pkg.publishConfig
+if (!publishConfig) {
+	console.log('  No publishConfig found, skipping manifest rewrite.')
+	process.exit(0)
+}
+
+// Backup the original file byte-for-byte
+copyFileSync(pkgPath, pkgPath + '.bak')
+console.log('  ✓ package.json backed up')
+
+for (const [field, value] of Object.entries(publishConfig)) {
+	pkg[field] = value
+}
+delete pkg.publishConfig
+
+writeFileSync(pkgPath, JSON.stringify(pkg, null, '    ') + '\n')
+console.log(`  ✓ Manifest rewritten for publish (${Object.keys(publishConfig).join(', ')})`)
+
+const root = join(process.cwd(), '../..')
+copyFileSync(join(root, 'LICENSE'), join(process.cwd(), 'LICENSE'))
+console.log('  ✓ LICENSE copied')
+
+if (pkg.name === 'page-agent') {
+	copyFileSync(join(root, 'README.md'), join(process.cwd(), 'README.md'))
+	console.log('  ✓ README.md copied')
+}
diff --git a/scripts/sync-version.js b/scripts/sync-version.js
new file mode 100644
index 0000000..7cf550b
--- /dev/null
+++ b/scripts/sync-version.js
@@ -0,0 +1,144 @@
+#!/usr/bin/env node
+/**
+ * Sync version from root package.json to all packages
+ *
+ * Usage:
+ *   node scripts/sync-version.js        # Sync current version from root
+ *   node scripts/sync-version.js 0.1.0  # Set root version, then sync all packages
+ */
+import chalk from 'chalk'
+import { existsSync, readFileSync, readdirSync, writeFileSync } from 'fs'
+import { dirname, join } from 'path'
+import { exit } from 'process'
+import { fileURLToPath } from 'url'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+const rootDir = join(__dirname, '..')
+
+const versionArg = process.argv[2]
+
+// Read root package.json
+const rootPkgPath = join(rootDir, 'package.json')
+const rootPkg = JSON.parse(readFileSync(rootPkgPath, 'utf-8'))
+const oldVersion = rootPkg.version
+const newVersion = versionArg ?? rootPkg.version
+
+if (!newVersion) {
+	console.log(chalk.yellow('⚠️  No version found in root package.json.\n'))
+	exit(1)
+}
+
+console.log(chalk.cyan.bold('\n📦 Syncing version\n'))
+
+// Update root package.json if new version specified
+if (versionArg) {
+	rootPkg.version = newVersion
+	writeFileSync(rootPkgPath, JSON.stringify(rootPkg, null, '    ') + '\n')
+	console.log(
+		chalk.green('✓') +
+			` ${chalk.bold('root')}: ${chalk.dim(oldVersion)} → ${chalk.yellow(newVersion)}`
+	)
+} else {
+	console.log(chalk.dim('  root:') + ` ${chalk.yellow(newVersion)} ${chalk.dim('(source)')}`)
+}
+
+// Sync to all packages
+const packagesDir = join(rootDir, 'packages')
+const packages = readdirSync(packagesDir, { withFileTypes: true })
+	.filter((d) => d.isDirectory())
+	.map((d) => d.name)
+
+let hasChanges = !!versionArg
+
+/**
+ * Check if a dependency name is a page-agent internal package
+ */
+function isInternalPackage(name) {
+	return name === 'page-agent' || name.startsWith('@page-agent/')
+}
+
+/**
+ * Update internal package versions in dependencies object
+ * @returns {boolean} Whether any changes were made
+ */
+function updateInternalDeps(deps, newVersion) {
+	if (!deps) return false
+	let changed = false
+	for (const [name, version] of Object.entries(deps)) {
+		if (isInternalPackage(name) && version !== newVersion) {
+			deps[name] = newVersion
+			changed = true
+		}
+	}
+	return changed
+}
+
+for (const pkg of packages) {
+	const pkgPath = join(packagesDir, pkg, 'package.json')
+	if (!existsSync(pkgPath)) continue
+
+	const pkgJson = JSON.parse(readFileSync(pkgPath, 'utf-8'))
+	let pkgChanged = false
+
+	// Update package version
+	if (pkgJson.version !== newVersion) {
+		pkgJson.version = newVersion
+		pkgChanged = true
+	}
+
+	// Update internal dependencies (dependencies only, devDeps keep "*")
+	if (updateInternalDeps(pkgJson.dependencies, newVersion)) {
+		pkgChanged = true
+	}
+
+	if (!pkgChanged) {
+		console.log(chalk.dim(`  ${pkgJson.name}: ${newVersion} (unchanged)`))
+		continue
+	}
+
+	writeFileSync(pkgPath, JSON.stringify(pkgJson, null, '    ') + '\n')
+	console.log(
+		chalk.green('✓') +
+			` ${chalk.bold(pkgJson.name)}: ${chalk.dim(oldVersion)} → ${chalk.yellow(newVersion)}`
+	)
+	hasChanges = true
+}
+
+// Update CDN URLs in documentation and source files
+const CDN_DEMO_URL_OLD = `https://cdn.jsdelivr.net/npm/page-agent@${oldVersion}/dist/iife/page-agent.demo.js`
+const CDN_DEMO_URL_NEW = `https://cdn.jsdelivr.net/npm/page-agent@${newVersion}/dist/iife/page-agent.demo.js`
+const CDN_DEMO_CN_URL_OLD = `https://registry.npmmirror.com/page-agent/${oldVersion}/files/dist/iife/page-agent.demo.js`
+const CDN_DEMO_CN_URL_NEW = `https://registry.npmmirror.com/page-agent/${newVersion}/files/dist/iife/page-agent.demo.js`
+
+const filesToUpdateCdn = ['README.md', 'docs/README-zh.md', 'packages/website/src/constants.ts']
+
+for (const relPath of filesToUpdateCdn) {
+	const filePath = join(rootDir, relPath)
+	if (!existsSync(filePath)) continue
+
+	let content = readFileSync(filePath, 'utf-8')
+	const original = content
+
+	content = content.replaceAll(CDN_DEMO_URL_OLD, CDN_DEMO_URL_NEW)
+	content = content.replaceAll(CDN_DEMO_CN_URL_OLD, CDN_DEMO_CN_URL_NEW)
+
+	if (content !== original) {
+		writeFileSync(filePath, content)
+		console.log(chalk.green('✓') + ` ${chalk.bold(relPath)}: CDN URLs updated`)
+		hasChanges = true
+	}
+}
+
+console.log(chalk.green.bold(`\n✓ Version synced: ${newVersion}\n`))
+
+// Show git commands hint
+if (hasChanges) {
+	const tagName = `v${newVersion}`
+	console.log(chalk.cyan.bold('📋 Next steps:\n'))
+	console.log(chalk.blueBright(`npm i`))
+	console.log(
+		chalk.blueBright(`git add . && git commit -m "chore(version): bump version to ${newVersion}"`)
+	)
+	console.log(chalk.blueBright(`git tag -a ${tagName} -m "${tagName}"`))
+	console.log(chalk.blueBright(`git push && git push origin ${tagName}\n`))
+}
diff --git a/tsconfig.base.json b/tsconfig.base.json
new file mode 100644
index 0000000..9519242
--- /dev/null
+++ b/tsconfig.base.json
@@ -0,0 +1,30 @@
+{
+    "compilerOptions": {
+        "target": "es2025",
+        "useDefineForClassFields": true,
+        "lib": ["ESNext", "DOM"],
+        "module": "esnext",
+        "skipLibCheck": true,
+        "allowJs": true,
+
+        "tsBuildInfoFile": "./node_modules/.tmp/tsconfig.tsbuildinfo",
+        "outDir": "dist",
+
+        /* Bundler mode */
+        "moduleResolution": "bundler",
+        "verbatimModuleSyntax": false,
+        "noEmit": true,
+        "jsx": "react-jsx",
+        "allowImportingTsExtensions": true,
+
+        /* Linting */
+        "strict": true,
+        "noUnusedLocals": false,
+        "noUnusedParameters": false,
+        "erasableSyntaxOnly": true,
+        "noFallthroughCasesInSwitch": true,
+        "noUncheckedSideEffectImports": true,
+
+        "types": ["node"]
+    }
+}
diff --git a/tsconfig.typecheck.json b/tsconfig.typecheck.json
new file mode 100644
index 0000000..7965ad8
--- /dev/null
+++ b/tsconfig.typecheck.json
@@ -0,0 +1,25 @@
+// Unified typecheck config for all lib/website packages.
+// Run: tsc --noEmit -p tsconfig.typecheck.json
+// Extension is checked separately (WXT has its own tsconfig base).
+//
+// With source-first package.json exports, TS resolves @page-agent/*
+// to sibling src/ via workspace symlinks — no paths mapping needed.
+{
+    "extends": "./tsconfig.base.json",
+    "compilerOptions": {
+        "composite": false,
+        "noEmit": true,
+        "tsBuildInfoFile": "./node_modules/.tmp/tsconfig.typecheck.tsbuildinfo",
+        "paths": {
+            "@/*": ["./packages/website/src/*"]
+        }
+    },
+    "include": [
+        "packages/llms/src/**/*",
+        "packages/page-controller/src/**/*",
+        "packages/ui/src/**/*",
+        "packages/core/src/**/*",
+        "packages/page-agent/src/**/*",
+        "packages/website/src/**/*"
+    ]
+}