chore(version): bump version to 1.0.0-beta.4

CODE_OF_CONDUCT.md

@@ -69,10 +69,10 @@ members of the project's leadership.
 
 ## Attribution
 
-This Code of Conduct is adapted from the [Contributor Covenant][https://www.contributor-covenant.org], version 1.4,
+This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org), version 1.4,
 available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html
 
-----
+---
 
 > Chinese Version
 > 《阿里巴巴开源行为准则》

README-zh.md

@@ -37,7 +37,7 @@
 
 ```html
 <script
-    src="https://registry.npmmirror.com/page-agent/1.0.0-beta.2/files/dist/iife/page-agent.demo.js"
+    src="https://registry.npmmirror.com/page-agent/1.0.0-beta.4/files/dist/iife/page-agent.demo.js"
     crossorigin="true"
 ></script>
 ```
@@ -46,8 +46,8 @@
 
 | 镜像   | URL                                                                                       |
 | ------ | ----------------------------------------------------------------------------------------- |
-| Global | https://cdn.jsdelivr.net/npm/page-agent@1.0.0-beta.2/dist/iife/page-agent.demo.js         |
+| Global | https://cdn.jsdelivr.net/npm/page-agent@1.0.0-beta.4/dist/iife/page-agent.demo.js         |
-| China  | https://registry.npmmirror.com/page-agent/1.0.0-beta.2/files/dist/iife/page-agent.demo.js |
+| China  | https://registry.npmmirror.com/page-agent/1.0.0-beta.4/files/dist/iife/page-agent.demo.js |
 
 ### NPM 安装
 

README.md

@@ -37,7 +37,7 @@ Fastest way to try PageAgent:
 
 ```html
 <script
-    src="https://cdn.jsdelivr.net/npm/page-agent@1.0.0-beta.2/dist/iife/page-agent.demo.js"
+    src="https://cdn.jsdelivr.net/npm/page-agent@1.0.0-beta.4/dist/iife/page-agent.demo.js"
     crossorigin="true"
 ></script>
 ```
@@ -46,8 +46,8 @@ Fastest way to try PageAgent:
 
 | Mirrors | URL                                                                                       |
 | ------- | ----------------------------------------------------------------------------------------- |
-| Global  | https://cdn.jsdelivr.net/npm/page-agent@1.0.0-beta.2/dist/iife/page-agent.demo.js         |
+| Global  | https://cdn.jsdelivr.net/npm/page-agent@1.0.0-beta.4/dist/iife/page-agent.demo.js         |
-| China   | https://registry.npmmirror.com/page-agent/1.0.0-beta.2/files/dist/iife/page-agent.demo.js |
+| China   | https://registry.npmmirror.com/page-agent/1.0.0-beta.4/files/dist/iife/page-agent.demo.js |
 
 ### NPM Installation
 

package-lock.json

@@ -1,12 +1,12 @@
 {
     "name": "root",
-    "version": "1.0.0-beta.2",
+    "version": "1.0.0-beta.4",
     "lockfileVersion": 3,
     "requires": true,
     "packages": {
         "": {
             "name": "root",
-            "version": "1.0.0-beta.2",
+            "version": "1.0.0-beta.4",
             "license": "MIT",
             "workspaces": [
                 "packages/page-controller",
@@ -8142,18 +8142,18 @@
         },
         "packages/core": {
             "name": "@page-agent/core",
-            "version": "1.0.0-beta.2",
+            "version": "1.0.0-beta.4",
             "license": "MIT",
             "dependencies": {
-                "@page-agent/llms": "1.0.0-beta.2",
+                "@page-agent/llms": "1.0.0-beta.4",
-                "@page-agent/page-controller": "1.0.0-beta.2",
+                "@page-agent/page-controller": "1.0.0-beta.4",
                 "chalk": "^5.6.2",
                 "zod": "^4.3.5"
             }
         },
         "packages/llms": {
             "name": "@page-agent/llms",
-            "version": "1.0.0-beta.2",
+            "version": "1.0.0-beta.4",
             "license": "MIT",
             "dependencies": {
                 "chalk": "^5.6.2",
@@ -8161,20 +8161,20 @@
             }
         },
         "packages/page-agent": {
-            "version": "1.0.0-beta.2",
+            "version": "1.0.0-beta.4",
             "license": "MIT",
             "dependencies": {
-                "@page-agent/core": "1.0.0-beta.2",
+                "@page-agent/core": "1.0.0-beta.4",
-                "@page-agent/llms": "1.0.0-beta.2",
+                "@page-agent/llms": "1.0.0-beta.4",
-                "@page-agent/page-controller": "1.0.0-beta.2",
+                "@page-agent/page-controller": "1.0.0-beta.4",
-                "@page-agent/ui": "1.0.0-beta.2",
+                "@page-agent/ui": "1.0.0-beta.4",
                 "chalk": "^5.6.2",
                 "zod": "^4.3.5"
             }
         },
         "packages/page-controller": {
             "name": "@page-agent/page-controller",
-            "version": "1.0.0-beta.2",
+            "version": "1.0.0-beta.4",
             "license": "MIT",
             "dependencies": {
                 "ai-motion": "^0.4.8"
@@ -8182,12 +8182,12 @@
         },
         "packages/ui": {
             "name": "@page-agent/ui",
-            "version": "1.0.0-beta.2",
+            "version": "1.0.0-beta.4",
             "license": "MIT"
         },
         "packages/website": {
             "name": "@page-agent/website",
-            "version": "1.0.0-beta.2",
+            "version": "1.0.0-beta.4",
             "dependencies": {
                 "@radix-ui/react-icons": "^1.3.2",
                 "@radix-ui/react-separator": "^1.1.8",

package.json

@@ -1,7 +1,7 @@
 {
     "name": "root",
     "private": true,
-    "version": "1.0.0-beta.2",
+    "version": "1.0.0-beta.4",
     "type": "module",
     "workspaces": [
         "packages/page-controller",

packages/core/package.json

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

packages/core/src/PageAgentCore.ts

@@ -26,6 +26,7 @@ import { assert } from './utils/assert'
 
 export { type PageAgentConfig }
 export { tool, type PageAgentTool } from './tools'
+export type * from './types'
 
 /**
  * AI agent for browser DOM automation.
@@ -263,6 +264,7 @@ export class PageAgentCore extends EventTarget {
 
 				this.history.push({
 					type: 'step',
+					stepIndex: step,
 					reflection,
 					action,
 					usage: result.usage,

packages/core/src/types.ts

@@ -35,6 +35,7 @@ export interface MacroToolResult {
  */
 export interface AgentStep {
 	type: 'step'
+	stepIndex: number
 	reflection: Partial<AgentReflection>
 	action: {
 		name: string

packages/llms/package.json

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

packages/page-agent/package.json

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

packages/page-controller/package.json

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

packages/page-controller/src/PageController.ts

@@ -80,6 +80,9 @@ export class PageController extends EventTarget {
 	/** 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
@@ -196,6 +199,9 @@ export class PageController extends EventTarget {
 		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'
@@ -215,11 +221,22 @@ export class PageController extends EventTarget {
 
 	// ======= 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. 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)
@@ -249,6 +266,7 @@ export class PageController extends EventTarget {
 	 */
 	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)
@@ -270,6 +288,7 @@ export class PageController extends EventTarget {
 	 */
 	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)
@@ -298,6 +317,8 @@ export class PageController extends EventTarget {
 		try {
 			const { down, numPages, pixels, index } = options
 
+			this.assertIndexed()
+
 			const scrollAmount = pixels ?? numPages * (down ? 1 : -1) * window.innerHeight
 
 			const element = index !== undefined ? getElementByIndex(this.selectorMap, index) : null
@@ -327,6 +348,8 @@ export class PageController extends EventTarget {
 		try {
 			const { right, pixels, index } = options
 
+			this.assertIndexed()
+
 			const scrollAmount = pixels * (right ? 1 : -1)
 
 			const element = index !== undefined ? getElementByIndex(this.selectorMap, index) : null
@@ -394,6 +417,7 @@ export class PageController extends EventTarget {
 		this.selectorMap.clear()
 		this.elementTextMap.clear()
 		this.simplifiedHTML = '<EMPTY>'
+		this.isIndexed = false
 		this.mask?.dispose()
 		this.mask = null
 	}

packages/ui/package.json

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

packages/ui/src/panel/Panel.ts

@@ -563,9 +563,8 @@ export class Panel {
 
 		// 2. Render each history event
 		const history = this.#agent.history
-		for (let i = 0; i < history.length; i++) {
+		for (const event of history) {
-			const event = history[i]
+			items.push(...this.#createHistoryCards(event))
-			items.push(...this.#createHistoryCards(event, i + 1))
 		}
 
 		this.#historySection.innerHTML = items.join('')
@@ -577,14 +576,17 @@ export class Panel {
 	}
 
 	/** Create cards for a history event */
-	#createHistoryCards(event: PanelAgentAdapter['history'][number], stepNumber: number): string[] {
+	#createHistoryCards(event: PanelAgentAdapter['history'][number]): string[] {
 		const cards: string[] = []
 		const time = formatTime(this.#config.language ?? 'en-US')
-		const meta = this.#i18n.t('ui.panel.step', {
+		const meta =
-			number: stepNumber.toString(),
+			event.type === 'step' && event.stepIndex !== undefined
+				? this.#i18n.t('ui.panel.step', {
+						number: (event.stepIndex + 1).toString(),
 						time,
 						duration: '',
 					})
+				: time
 
 		if (event.type === 'step') {
 			// Reflection card

packages/ui/src/panel/types.ts

@@ -34,6 +34,7 @@ export interface PanelAgentAdapter extends EventTarget {
 	/** History of agent events */
 	readonly history: readonly {
 		type: 'step' | 'observation' | 'user_takeover' | 'error'
+		stepIndex?: number
 		/** For 'step' type */
 		reflection?: {
 			evaluation_previous_goal?: string

packages/website/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@page-agent/website",
     "private": true,
-    "version": "1.0.0-beta.2",
+    "version": "1.0.0-beta.4",
     "type": "module",
     "scripts": {
         "dev": "vite --host 0.0.0.0",

packages/website/src/constants.ts

@@ -1,8 +1,8 @@
 // Demo build (auto-init with demo LLM, for quick testing)
 export const CDN_DEMO_URL =
-	'https://cdn.jsdelivr.net/npm/page-agent@1.0.0-beta.2/dist/iife/page-agent.demo.js'
+	'https://cdn.jsdelivr.net/npm/page-agent@1.0.0-beta.4/dist/iife/page-agent.demo.js'
 export const CDN_DEMO_CN_URL =
-	'https://registry.npmmirror.com/page-agent/1.0.0-beta.2/files/dist/iife/page-agent.demo.js'
+	'https://registry.npmmirror.com/page-agent/1.0.0-beta.4/files/dist/iife/page-agent.demo.js'
 
 // Demo LLM for website testing
 export const DEMO_MODEL = 'PAGE-AGENT-FREE-TESTING-RANDOM'