From 1454d1514264cd1ab8bab6e7df6adaafa435ec61 Mon Sep 17 00:00:00 2001
From: Usman Baig <mubaig@pm.me>
Date: Wed, 11 Feb 2026 14:13:05 +0100
Subject: [PATCH] docs: clarify default and optional data-storage options in
 ScriptSetupBlock and script.js for improved user understanding

---
 components/sites/ScriptSetupBlock.tsx |  2 +-
 public/script.js                      | 20 +++++++++++++++++---
 2 files changed, 18 insertions(+), 4 deletions(-)

diff --git a/components/sites/ScriptSetupBlock.tsx b/components/sites/ScriptSetupBlock.tsx
index e14756e..e12a373 100644
--- a/components/sites/ScriptSetupBlock.tsx
+++ b/components/sites/ScriptSetupBlock.tsx
@@ -90,7 +90,7 @@ export default function ScriptSetupBlock({
           {`<script defer data-domain="${site.domain}" data-api="${API_URL}" src="${APP_URL}/script.js"></script>`}
         </code>
         <p className="mt-2 text-xs text-neutral-500 dark:text-neutral-400">
-          Optional: <code className="rounded px-1 bg-neutral-200 dark:bg-neutral-700">data-storage=&quot;session&quot;</code> for per-tab (ephemeral) visitor counting.
+          Default: cross-tab (localStorage). Optional: <code className="rounded px-1 bg-neutral-200 dark:bg-neutral-700">data-storage=&quot;session&quot;</code> to opt out (per-tab, ephemeral).
         </p>
         <button
           type="button"
diff --git a/public/script.js b/public/script.js
index 7fd4aca..24857c4 100644
--- a/public/script.js
+++ b/public/script.js
@@ -1,7 +1,7 @@
 /**
  * Pulse - Privacy-First Tracking Script
  * Lightweight, no cookies, GDPR compliant.
- * Default: cross-tab visitor ID (localStorage, optional data-storage-ttl in hours).
+ * Default: cross-tab visitor ID (localStorage), optional data-storage-ttl in hours.
  * Optional: data-storage="session" for per-tab (ephemeral) counting.
  */
 
@@ -116,8 +116,8 @@
     return Math.random().toString(36).substring(2, 15) + Math.random().toString(36).substring(2, 15);
   }
 
-  // * Returns session/visitor ID. Default: ephemeral (sessionStorage, per-tab).
-  // * With data-storage="local": persistent (localStorage, cross-tab), optional TTL in hours.
+  // * Returns session/visitor ID. Default: persistent (localStorage, cross-tab), optional TTL in hours.
+  // * With data-storage="session": ephemeral (sessionStorage, per-tab).
   function getSessionId() {
     if (cachedSessionId) {
       return cachedSessionId;
@@ -158,6 +158,20 @@
             }
           } catch (e2) {}
         }
+        // * Final re-read immediately before write to avoid overwriting a fresher ID from another tab
+        var rawBeforeWrite = localStorage.getItem(key);
+        if (rawBeforeWrite) {
+          try {
+            var parsedBefore = JSON.parse(rawBeforeWrite);
+            if (parsedBefore && typeof parsedBefore.id === 'string') {
+              var expBefore = ttlMs > 0 && typeof parsedBefore.created === 'number' && (Date.now() - parsedBefore.created > ttlMs);
+              if (!expBefore) {
+                cachedSessionId = parsedBefore.id;
+                return cachedSessionId;
+              }
+            }
+          } catch (e3) {}
+        }
         localStorage.setItem(key, JSON.stringify({ id: cachedSessionId, created: Date.now() }));
       } catch (e) {
         cachedSessionId = generateId();