fix: persist document.referrer when doing page refresh (#28)

Author: theskillwithin

src/index.ts

@@ -116,7 +116,12 @@ function checkClientHints() {
 	if (cookieChanged) {
 		// Increment reload attempts counter
 		sessionStorage.setItem('clientHintReloadAttempts', String(reloadAttempts + 1));
-		
+
+		// Preserve document.referrer before reload so analytics tools can access it
+		if (document.referrer) {
+			sessionStorage.setItem('clientHintReferrer', document.referrer);
+		}
+
 		// Hide the page content immediately to prevent visual flicker
 		const style = document.createElement('style');
 		style.textContent = 'html { visibility: hidden !important; }';
@@ -127,6 +132,16 @@ function checkClientHints() {
 	} else {
 		// Reset reload attempts counter if no reload was needed
 		sessionStorage.removeItem('clientHintReloadAttempts');
+
+		// Restore document.referrer if it was preserved from a client-hint reload
+		const savedReferrer = sessionStorage.getItem('clientHintReferrer');
+		if (savedReferrer) {
+			sessionStorage.removeItem('clientHintReferrer');
+			Object.defineProperty(document, 'referrer', {
+				value: savedReferrer,
+				configurable: true,
+			});
+		}
 	}
 }
 

test/index.test.ts

@@ -191,3 +191,39 @@ test('client script includes infinite refresh prevention', () => {
 	assert.ok(checkScript.includes('catch'))
 	assert.ok(checkScript.includes('decodeURIComponent'))
 })
+
+test('client script preserves document.referrer across reloads', () => {
+	const hints = getHintUtils({
+		colorScheme: colorSchemeHint,
+		timeZone: timeZoneHint,
+		reducedMotion: reducedMotionHint,
+	})
+
+	const checkScript = hints.getClientHintCheckScript()
+
+	// Should save document.referrer to sessionStorage before reload
+	assert.ok(
+		checkScript.includes('clientHintReferrer'),
+		'script should use clientHintReferrer sessionStorage key',
+	)
+	assert.ok(
+		checkScript.includes("sessionStorage.setItem('clientHintReferrer'"),
+		'script should save referrer to sessionStorage before reload',
+	)
+	assert.ok(
+		checkScript.includes("sessionStorage.getItem('clientHintReferrer')"),
+		'script should read saved referrer from sessionStorage after reload',
+	)
+
+	// Should restore document.referrer via Object.defineProperty
+	assert.ok(
+		checkScript.includes("Object.defineProperty(document, 'referrer'"),
+		'script should restore document.referrer via Object.defineProperty',
+	)
+
+	// Should clean up sessionStorage after restoring
+	assert.ok(
+		checkScript.includes("sessionStorage.removeItem('clientHintReferrer')"),
+		'script should remove saved referrer from sessionStorage after restoring',
+	)
+})