feat: custom PageController; remove beforeunload; node-safe PageController

packages/page-agent/src/PageAgent.ts

@@ -68,7 +68,6 @@ export class PageAgent extends EventTarget {
 
 	#llm: LLM
 	#abortController = new AbortController()
-	#beforeUnloadListener: ((e: Event) => void) | null = null
 
 	/** PageController for DOM operations */
 	pageController: PageController
@@ -92,10 +91,12 @@ export class PageAgent extends EventTarget {
 		this.tools = new Map(tools)
 
 		// Initialize PageController with config (mask enabled by default)
-		this.pageController = new PageController({
-			...this.config,
-			enableMask: this.config.enableMask ?? true,
-		})
+		this.pageController =
+			this.config.pageController ??
+			new PageController({
+				...this.config,
+				enableMask: this.config.enableMask ?? true,
+			})
 
 		// Listen to LLM retry events
 		this.#llm.addEventListener('retry', (e) => {
@@ -137,11 +138,6 @@ export class PageAgent extends EventTarget {
 		if (!this.config.experimentalScriptExecutionTool) {
 			this.tools.delete('execute_javascript')
 		}
-
-		this.#beforeUnloadListener = (e) => {
-			if (!this.disposed) this.dispose('PAGE_UNLOADING')
-		}
-		window.addEventListener('beforeunload', this.#beforeUnloadListener)
 	}
 
 	/** Get current agent status */
@@ -591,12 +587,6 @@ export class PageAgent extends EventTarget {
 		this.history = []
 		this.#abortController.abort(reason ?? 'PageAgent disposed')
 
-		// Clean up window event listeners
-		if (this.#beforeUnloadListener) {
-			window.removeEventListener('beforeunload', this.#beforeUnloadListener)
-			this.#beforeUnloadListener = null
-		}
-
 		// Emit dispose event for UI cleanup
 		this.dispatchEvent(new Event('dispose'))
 

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

@@ -1,5 +1,5 @@
 import type { LLMConfig } from '@page-agent/llms'
-import type { PageControllerConfig } from '@page-agent/page-controller'
+import type { PageController, PageControllerConfig } from '@page-agent/page-controller'
 
 import type { PageAgent } from '../PageAgent'
 import type { PageAgentTool } from '../tools'
@@ -74,7 +74,6 @@ export interface AgentConfig {
 
 	/**
 	 * @note this hook can block the disposal process
-	 * @note when dispose caused by page unload, reason will be 'PAGE_UNLOADING'. this method CANNOT block unloading. async operations may be cut.
 	 * @todo remove `this` binding, pass agent as explicit parameter instead
 	 */
 	onDispose?: (this: PageAgent, reason?: string) => void
@@ -105,6 +104,13 @@ export interface AgentConfig {
 	 */
 	transformPageContent?: (content: string) => Promise<string> | string
 
+	/**
+	 * @experimental
+	 * Custom PageController instance to control page navigation and actions
+	 * @note If not provided, a default PageController will be created
+	 */
+	pageController?: PageController
+
 	/**
 	 * TODO: @unimplemented
 	 * hook when action causes a new page to be opened