From 450dd8cb02395c2777ac73d6e2796f91effb6bf7 Mon Sep 17 00:00:00 2001
From: Julian Schoen <julian@echelonai.com>
Date: Thu, 2 Apr 2026 14:48:39 +0200
Subject: [PATCH] feat: add auto-cleanup for visual tracer overlays on
 navigation

Add attachAutoCleanup(page) method that listens to framenavigated
events and removes stale overlays, preventing visual artifacts when
pages navigate while overlays are visible.
---
 packages/core/src/viewport/visual-tracer.ts | 15 +++++++++++++++
 1 file changed, 15 insertions(+)

diff --git a/packages/core/src/viewport/visual-tracer.ts b/packages/core/src/viewport/visual-tracer.ts
index 5a8db5f..74f0f2b 100644
--- a/packages/core/src/viewport/visual-tracer.ts
+++ b/packages/core/src/viewport/visual-tracer.ts
@@ -978,4 +978,19 @@ export class VisualTracer {
 			{ attr: OVERLAY_ATTR },
 		);
 	}
+
+	/**
+	 * Attaches automatic overlay cleanup on page navigation.
+	 * Call once per page to ensure overlays don't persist across navigations.
+	 * Returns a cleanup function to detach the listener.
+	 */
+	attachAutoCleanup(page: Page): () => void {
+		const handler = () => {
+			this.clearOverlays(page).catch(() => {});
+		};
+		page.on('framenavigated', handler);
+		return () => {
+			page.off('framenavigated', handler);
+		};
+	}
 }