Restart clarity when page is loaded from bfcache

Manu Nair · Manu Nair · commit 51cae6549cbc · 2025-12-23T15:37:21.000-08:00
diff --git a/lerna.json b/lerna.json
@@ -2,6 +2,6 @@
   "packages": [
     "packages/*"
   ],
-  "version": "0.8.47",
+  "version": "0.8.47-beta",
   "npmClient": "yarn"
 }
diff --git a/package.json b/package.json
@@ -1,7 +1,7 @@
 {
   "name": "clarity",
   "private": true,
-  "version": "0.8.47",
+  "version": "0.8.47-beta",
   "repository": "https://github.com/microsoft/clarity.git",
   "author": "Sarvesh Nagpal <sarveshn@microsoft.com>",
   "license": "MIT",
diff --git a/packages/clarity-decode/package.json b/packages/clarity-decode/package.json
@@ -1,6 +1,6 @@
 {
   "name": "clarity-decode",
-  "version": "0.8.47",
+  "version": "0.8.47-beta",
   "description": "An analytics library that uses web page interactions to generate aggregated insights",
   "author": "Microsoft Corp.",
   "license": "MIT",
@@ -26,7 +26,7 @@
     "url": "https://github.com/Microsoft/clarity/issues"
   },
   "dependencies": {
-    "clarity-js": "^0.8.47"
+    "clarity-js": "^0.8.47-beta"
   },
   "devDependencies": {
     "@rollup/plugin-commonjs": "^24.0.0",
diff --git a/packages/clarity-devtools/package.json b/packages/clarity-devtools/package.json
@@ -1,6 +1,6 @@
 {
   "name": "clarity-devtools",
-  "version": "0.8.47",
+  "version": "0.8.47-beta",
   "private": true,
   "description": "Adds Clarity debugging support to browser devtools",
   "author": "Microsoft Corp.",
@@ -24,9 +24,9 @@
     "url": "https://github.com/Microsoft/clarity/issues"
   },
   "dependencies": {
-    "clarity-decode": "^0.8.47",
-    "clarity-js": "^0.8.47",
-    "clarity-visualize": "^0.8.47"
+    "clarity-decode": "^0.8.47-beta",
+    "clarity-js": "^0.8.47-beta",
+    "clarity-visualize": "^0.8.47-beta"
   },
   "devDependencies": {
     "@rollup/plugin-node-resolve": "^15.0.0",
diff --git a/packages/clarity-devtools/static/manifest.json b/packages/clarity-devtools/static/manifest.json
@@ -2,8 +2,8 @@
   "manifest_version": 3,
   "name": "Microsoft Clarity Developer Tools",
   "description": "Clarity helps you understand how users are interacting with your website.",
-  "version": "0.8.47",
-  "version_name": "0.8.47",
+  "version": "0.8.47-beta",
+  "version_name": "0.8.47-beta",
   "minimum_chrome_version": "88",
   "devtools_page": "devtools.html",
   "icons": {
diff --git a/packages/clarity-js/package.json b/packages/clarity-js/package.json
@@ -1,6 +1,6 @@
 {
   "name": "clarity-js",
-  "version": "0.8.47",
+  "version": "0.8.47-beta",
   "description": "An analytics library that uses web page interactions to generate aggregated insights",
   "author": "Microsoft Corp.",
   "license": "MIT",
diff --git a/packages/clarity-js/src/core/version.ts b/packages/clarity-js/src/core/version.ts
@@ -1,2 +1,2 @@
-let version = "0.8.47";
+let version = "0.8.47-beta";
 export default version;
diff --git a/packages/clarity-js/src/interaction/index.ts b/packages/clarity-js/src/interaction/index.ts
@@ -11,6 +11,7 @@ import * as timeline from "@src/interaction/timeline";
 import * as unload from "@src/interaction/unload";
 import * as visibility from "@src/interaction/visibility";
 import * as focus from "@src/interaction/focus";
+import * as pageshow from "@src/interaction/pageshow";
 
 export function start(): void {
     timeline.start();
@@ -21,6 +22,7 @@ export function start(): void {
     resize.start();
     visibility.start();
     focus.start();
+    pageshow.start();
     scroll.start();
     selection.start();
     change.start();
@@ -37,6 +39,7 @@ export function stop(): void {
     resize.stop();
     visibility.stop();
     focus.stop();
+    pageshow.stop();
     scroll.stop();
     selection.stop();
     change.stop();
diff --git a/packages/clarity-js/src/interaction/pageshow.ts b/packages/clarity-js/src/interaction/pageshow.ts
@@ -0,0 +1,35 @@
+import { Constant } from "@clarity-types/core";
+import { Code, Severity } from "@clarity-types/data";
+import * as clarity from "@src/clarity";
+import api from "@src/core/api";
+import measure from "@src/core/measure";
+import * as internal from "@src/diagnostic/internal";
+
+let bound = false;
+
+export function start(): void {
+    // Only bind once - this listener must persist even when Clarity stops
+    // to detect when the page is restored from bfcache
+    if (!bound) {
+        try {
+            window[api(Constant.AddEventListener)]("pageshow", measure(handler) as EventListener, { capture: false, passive: true });
+            bound = true;
+        } catch {
+            /* do nothing */
+        }
+    }
+}
+
+function handler(evt: PageTransitionEvent): void {
+    // The persisted property indicates if the page was loaded from bfcache
+    if (evt && evt.persisted) {
+        // Restart Clarity since it was stopped when the page entered bfcache
+        clarity.start();
+        internal.log(Code.BFCache, Severity.Info);
+    }
+}
+
+export function stop(): void {
+    // Intentionally don't remove the listener or reset 'bound' flag
+    // We need the listener to persist to detect bfcache restoration
+}
diff --git a/packages/clarity-js/types/data.d.ts b/packages/clarity-js/types/data.d.ts
@@ -212,6 +212,7 @@ export const enum Code {
     Config = 8,
     FunctionExecutionTime = 9,
     LeanLimit = 10,
+    BFCache = 11,
 }
 
 export const enum Severity {
diff --git a/packages/clarity-visualize/package.json b/packages/clarity-visualize/package.json
@@ -1,6 +1,6 @@
 {
   "name": "clarity-visualize",
-  "version": "0.8.47",
+  "version": "0.8.47-beta",
   "description": "An analytics library that uses web page interactions to generate aggregated insights",
   "author": "Microsoft Corp.",
   "license": "MIT",
@@ -27,7 +27,7 @@
     "url": "https://github.com/Microsoft/clarity/issues"
   },
   "dependencies": {
-    "clarity-decode": "^0.8.47"
+    "clarity-decode": "^0.8.47-beta"
   },
   "devDependencies": {
     "@rollup/plugin-commonjs": "^24.0.0",
diff --git a/test/bfcache.test.ts b/test/bfcache.test.ts
@@ -0,0 +1,45 @@
+import { test, expect } from '@playwright/test';
+import { markup } from './helper';
+import { decode } from 'clarity-decode';
+
+test.describe('BFCache Tests', () => {
+    test('should log BFCache diagnostic event when pageshow fires with persisted=true', async ({ page }) => {
+        // Load the test page and get initial payloads
+        await markup(page, "core.html");
+        
+        // Stop Clarity to simulate pagehide behavior
+        await page.evaluate(() => {
+            window.clarity('stop');
+        });
+
+        await page.waitForTimeout(100);
+        
+        // Simulate bfcache restoration by dispatching a pageshow event with persisted=true
+        await page.evaluate(() => {
+            const event = new PageTransitionEvent('pageshow', { persisted: true });
+            window.dispatchEvent(event);
+        });
+
+        // Wait for event processing
+        await page.waitForTimeout(500);
+
+        // Get all payloads including the new one
+        const allPayloads = await page.evaluate('window.payloads') as string[];
+        const decoded = allPayloads.map((x: string) => decode(x));
+        
+        // Look for diagnostic log with BFCache code (11)
+        let foundBFCacheLog = false;
+        for (const payload of decoded) {
+            if (payload.log) {
+                for (const log of payload.log) {
+                    if (log.data?.code === 11) { // Code.BFCache = 11
+                        foundBFCacheLog = true;
+                        expect(log.data.severity).toBe(0); // Severity.Info = 0
+                    }
+                }
+            }
+        }
+
+        expect(foundBFCacheLog).toBe(true);
+    });
+});

Original file line number	Diff line number	Diff line change
`@@ -2,6 +2,6 @@`
`2`	`2`	`"packages": [`
`3`	`3`	`"packages/*"`
`4`	`4`	`],`
`5`		`- "version": "0.8.47",`
	`5`	`+ "version": "0.8.47-beta",`
`6`	`6`	`"npmClient": "yarn"`
`7`	`7`	`}`
Original file line number	Diff line number	Diff line change
`@@ -1,7 +1,7 @@`
`1`	`1`	`{`
`2`	`2`	`"name": "clarity",`
`3`	`3`	`"private": true,`
`4`		`- "version": "0.8.47",`
	`4`	`+ "version": "0.8.47-beta",`
`5`	`5`	`"repository": "https://github.com/microsoft/clarity.git",`
`6`	`6`	`"author": "Sarvesh Nagpal <sarveshn@microsoft.com>",`
`7`	`7`	`"license": "MIT",`
Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,6 @@`
`1`	`1`	`{`
`2`	`2`	`"name": "clarity-js",`
`3`		`- "version": "0.8.47",`
	`3`	`+ "version": "0.8.47-beta",`
`4`	`4`	`"description": "An analytics library that uses web page interactions to generate aggregated insights",`
`5`	`5`	`"author": "Microsoft Corp.",`
`6`	`6`	`"license": "MIT",`
Original file line number	Diff line number	Diff line change
`@@ -1,2 +1,2 @@`
`1`		`-let version = "0.8.47";`
	`1`	`+let version = "0.8.47-beta";`
`2`	`2`	`export default version;`
Original file line number	Diff line number	Diff line change
`@@ -212,6 +212,7 @@ export const enum Code {`
`212`	`212`	`Config = 8,`
`213`	`213`	`FunctionExecutionTime = 9,`
`214`	`214`	`LeanLimit = 10,`
	`215`	`+ BFCache = 11,`
`215`	`216`	`}`
`216`	`217`
`217`	`218`	`export const enum Severity {`