From c20963fc74aef2a581d3a59959ba1558d5d1431c Mon Sep 17 00:00:00 2001
From: Usman Baig <mubaig@pm.me>
Date: Wed, 11 Feb 2026 10:17:25 +0100
Subject: [PATCH 01/18] chore: update version to 0.1.0-alpha in package.json

---
 package.json | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/package.json b/package.json
index 98ab95e..1af99b0 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "pulse-frontend",
-  "version": "0.1.0",
+  "version": "0.1.0-alpha",
   "private": true,
   "scripts": {
     "dev": "next dev",
-- 
2.49.1


From c827e823764cb92ad949b29c619ce1c52cb9f476 Mon Sep 17 00:00:00 2001
From: Usman Baig <mubaig@pm.me>
Date: Wed, 11 Feb 2026 10:57:01 +0100
Subject: [PATCH 02/18] feat: enhance ScriptSetupBlock and script.js with
 optional persistent visitor ID storage

---
 components/sites/ScriptSetupBlock.tsx |  3 ++
 public/script.js                      | 53 ++++++++++++++++++++++-----
 2 files changed, 46 insertions(+), 10 deletions(-)

diff --git a/components/sites/ScriptSetupBlock.tsx b/components/sites/ScriptSetupBlock.tsx
index 4d16d76..7f4c0ce 100644
--- a/components/sites/ScriptSetupBlock.tsx
+++ b/components/sites/ScriptSetupBlock.tsx
@@ -89,6 +89,9 @@ export default function ScriptSetupBlock({
         <code className="text-xs text-neutral-900 dark:text-white break-all font-mono block pr-10">
           {`<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;local&quot;</code> for cross-tab unique visitors; <code className="rounded px-1 bg-neutral-200 dark:bg-neutral-700">data-storage-ttl=&quot;24&quot;</code> (hours) to expire the ID.
+        </p>
         <button
           type="button"
           onClick={copyScript}
diff --git a/public/script.js b/public/script.js
index 307a65e..da88ad3 100644
--- a/public/script.js
+++ b/public/script.js
@@ -1,6 +1,8 @@
 /**
  * Pulse - Privacy-First Tracking Script
- * Lightweight, no cookies, GDPR compliant
+ * Lightweight, no cookies, GDPR compliant.
+ * Default: ephemeral session ID (sessionStorage, per-tab). Optional: data-storage="local"
+ * and data-storage-ttl (hours) for a persistent cross-tab visitor ID with optional expiry.
  */
 
 (function() {
@@ -19,6 +21,11 @@
 
   const domain = script.getAttribute('data-domain');
   const apiUrl = script.getAttribute('data-api') || 'https://pulse-api.ciphera.net';
+  // * Visitor ID storage: "session" (default, ephemeral per-tab) or "local" (persistent, cross-tab)
+  const storageMode = (script.getAttribute('data-storage') || 'session').toLowerCase() === 'local' ? 'local' : 'session';
+  // * When storage is "local", optional TTL in hours; after TTL the ID is regenerated (e.g. 24 = one day)
+  const ttlHours = storageMode === 'local' ? parseFloat(script.getAttribute('data-storage-ttl') || '24', 10) : 0;
+  const ttlMs = ttlHours > 0 ? ttlHours * 60 * 60 * 1000 : 0;
 
   // * Performance Monitoring (Core Web Vitals) State
   let currentEventId = null;
@@ -102,25 +109,51 @@
     }
   });
 
-  // * Memory cache for session ID (fallback if sessionStorage is unavailable)
+  // * Memory cache for session ID (fallback if storage is unavailable)
   let cachedSessionId = null;
 
-  // * Generate ephemeral session ID (not persistent)
+  function generateId() {
+    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.
   function getSessionId() {
     if (cachedSessionId) {
       return cachedSessionId;
     }
 
-    // * Use a static key for session storage to ensure consistency across pages
     const key = 'ciphera_session_id';
-    // * Legacy key support for migration (strip whitespace just in case)
     const legacyKey = 'plausible_session_' + (domain ? domain.trim() : '');
 
-    try {
-      // * Try to get existing session ID
-      cachedSessionId = sessionStorage.getItem(key);
+    if (storageMode === 'local') {
+      try {
+        const raw = localStorage.getItem(key);
+        if (raw) {
+          try {
+            const parsed = JSON.parse(raw);
+            if (parsed && typeof parsed.id === 'string') {
+              const expired = ttlMs > 0 && typeof parsed.created === 'number' && (Date.now() - parsed.created > ttlMs);
+              if (!expired) {
+                cachedSessionId = parsed.id;
+                return cachedSessionId;
+              }
+            }
+          } catch (e) {
+            // * Invalid JSON or old string format: treat as expired and regenerate
+          }
+        }
+        cachedSessionId = generateId();
+        localStorage.setItem(key, JSON.stringify({ id: cachedSessionId, created: Date.now() }));
+      } catch (e) {
+        cachedSessionId = generateId();
+      }
+      return cachedSessionId;
+    }
 
-      // * If not found in new key, try legacy key and migrate
+    // * Default: session storage (ephemeral, per-tab)
+    try {
+      cachedSessionId = sessionStorage.getItem(key);
       if (!cachedSessionId && legacyKey) {
         cachedSessionId = sessionStorage.getItem(legacyKey);
         if (cachedSessionId) {
@@ -133,7 +166,7 @@
     }
 
     if (!cachedSessionId) {
-      cachedSessionId = Math.random().toString(36).substring(2, 15) + Math.random().toString(36).substring(2, 15);
+      cachedSessionId = generateId();
       try {
         sessionStorage.setItem(key, cachedSessionId);
       } catch (e) {
-- 
2.49.1


From f1c27e458a5996919069349655afa980df496ebc Mon Sep 17 00:00:00 2001
From: Usman Baig <mubaig@pm.me>
Date: Wed, 11 Feb 2026 11:06:27 +0100
Subject: [PATCH 03/18] feat: update ScriptSetupBlock and script.js to support
 new visitor ID storage options

---
 components/sites/ScriptSetupBlock.tsx |  6 +++---
 public/script.js                      | 10 +++++-----
 2 files changed, 8 insertions(+), 8 deletions(-)

diff --git a/components/sites/ScriptSetupBlock.tsx b/components/sites/ScriptSetupBlock.tsx
index 7f4c0ce..a7a83a0 100644
--- a/components/sites/ScriptSetupBlock.tsx
+++ b/components/sites/ScriptSetupBlock.tsx
@@ -40,7 +40,7 @@ export default function ScriptSetupBlock({
   const [scriptCopied, setScriptCopied] = useState(false)
 
   const copyScript = useCallback(() => {
-    const script = `<script defer data-domain="${site.domain}" data-api="${API_URL}" src="${APP_URL}/script.js"></script>`
+    const script = `<script defer data-domain="${site.domain}" data-api="${API_URL}" data-storage="local" data-storage-ttl="24" src="${APP_URL}/script.js"></script>`
     navigator.clipboard.writeText(script)
     setScriptCopied(true)
     toast.success('Script copied to clipboard')
@@ -87,10 +87,10 @@ export default function ScriptSetupBlock({
 
       <div className="rounded-xl bg-neutral-100 dark:bg-neutral-800 p-4 relative group">
         <code className="text-xs text-neutral-900 dark:text-white break-all font-mono block pr-10">
-          {`<script defer data-domain="${site.domain}" data-api="${API_URL}" src="${APP_URL}/script.js"></script>`}
+          {`<script defer data-domain="${site.domain}" data-api="${API_URL}" data-storage="local" data-storage-ttl="24" 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;local&quot;</code> for cross-tab unique visitors; <code className="rounded px-1 bg-neutral-200 dark:bg-neutral-700">data-storage-ttl=&quot;24&quot;</code> (hours) to expire the ID.
+          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.
         </p>
         <button
           type="button"
diff --git a/public/script.js b/public/script.js
index da88ad3..ebed672 100644
--- a/public/script.js
+++ b/public/script.js
@@ -1,8 +1,8 @@
 /**
  * Pulse - Privacy-First Tracking Script
  * Lightweight, no cookies, GDPR compliant.
- * Default: ephemeral session ID (sessionStorage, per-tab). Optional: data-storage="local"
- * and data-storage-ttl (hours) for a persistent cross-tab visitor ID with optional expiry.
+ * Default: cross-tab visitor ID (localStorage, optional data-storage-ttl in hours).
+ * Optional: data-storage="session" for per-tab (ephemeral) counting.
  */
 
 (function() {
@@ -21,8 +21,8 @@
 
   const domain = script.getAttribute('data-domain');
   const apiUrl = script.getAttribute('data-api') || 'https://pulse-api.ciphera.net';
-  // * Visitor ID storage: "session" (default, ephemeral per-tab) or "local" (persistent, cross-tab)
-  const storageMode = (script.getAttribute('data-storage') || 'session').toLowerCase() === 'local' ? 'local' : 'session';
+  // * Visitor ID storage: "local" (default, cross-tab) or "session" (ephemeral per-tab)
+  const storageMode = (script.getAttribute('data-storage') || 'local').toLowerCase() === 'session' ? 'session' : 'local';
   // * When storage is "local", optional TTL in hours; after TTL the ID is regenerated (e.g. 24 = one day)
   const ttlHours = storageMode === 'local' ? parseFloat(script.getAttribute('data-storage-ttl') || '24', 10) : 0;
   const ttlMs = ttlHours > 0 ? ttlHours * 60 * 60 * 1000 : 0;
@@ -151,7 +151,7 @@
       return cachedSessionId;
     }
 
-    // * Default: session storage (ephemeral, per-tab)
+    // * data-storage="session": session storage (ephemeral, per-tab)
     try {
       cachedSessionId = sessionStorage.getItem(key);
       if (!cachedSessionId && legacyKey) {
-- 
2.49.1


From 2b3d052f87cdec1637ef9837241a7e63e4cc3715 Mon Sep 17 00:00:00 2001
From: Usman Baig <mubaig@pm.me>
Date: Wed, 11 Feb 2026 11:20:05 +0100
Subject: [PATCH 04/18] feat: add logging for session ID management in
 script.js to enhance debugging and monitoring

---
 public/script.js | 25 +++++++++++++++++++++++++
 1 file changed, 25 insertions(+)

diff --git a/public/script.js b/public/script.js
index ebed672..103b820 100644
--- a/public/script.js
+++ b/public/script.js
@@ -26,6 +26,11 @@
   // * When storage is "local", optional TTL in hours; after TTL the ID is regenerated (e.g. 24 = one day)
   const ttlHours = storageMode === 'local' ? parseFloat(script.getAttribute('data-storage-ttl') || '24', 10) : 0;
   const ttlMs = ttlHours > 0 ? ttlHours * 60 * 60 * 1000 : 0;
+  // #region agent log
+  try {
+    fetch('http://127.0.0.1:7243/ingest/50587964-c1c6-436a-a7ce-ff2cde3c5b63',{method:'POST',headers:{'Content-Type':'application/json'},body:JSON.stringify({location:'script.js:init',message:'storage config',data:{storageMode,dataStorageAttr:script.getAttribute('data-storage'),ttlHours,ttlMs,domain},timestamp:Date.now(),hypothesisId:'A,B'})}).catch(function(){});
+  } catch (e) {}
+  // #endregion
 
   // * Performance Monitoring (Core Web Vitals) State
   let currentEventId = null;
@@ -120,6 +125,9 @@
   // * With data-storage="local": persistent (localStorage, cross-tab), optional TTL in hours.
   function getSessionId() {
     if (cachedSessionId) {
+      // #region agent log
+      try { fetch('http://127.0.0.1:7243/ingest/50587964-c1c6-436a-a7ce-ff2cde3c5b63',{method:'POST',headers:{'Content-Type':'application/json'},body:JSON.stringify({location:'script.js:getSessionId',message:'return cached',data:{sessionIdPrefix:cachedSessionId.substring(0,8),storageMode},timestamp:Date.now(),hypothesisId:'E'})}).catch(function(){}); } catch (e) {}
+      // #endregion
       return cachedSessionId;
     }
 
@@ -129,6 +137,11 @@
     if (storageMode === 'local') {
       try {
         const raw = localStorage.getItem(key);
+        // #region agent log
+        var rawType = raw === null ? 'null' : typeof raw;
+        var rawPrefix = raw && raw.substring ? raw.substring(0, 60) : '';
+        try { fetch('http://127.0.0.1:7243/ingest/50587964-c1c6-436a-a7ce-ff2cde3c5b63',{method:'POST',headers:{'Content-Type':'application/json'},body:JSON.stringify({location:'script.js:getSessionId:local',message:'localStorage read',data:{rawType,rawPrefix,hasRaw:!!raw},timestamp:Date.now(),hypothesisId:'C,D,E'})}).catch(function(){}); } catch (e) {}
+        // #endregion
         if (raw) {
           try {
             const parsed = JSON.parse(raw);
@@ -136,6 +149,9 @@
               const expired = ttlMs > 0 && typeof parsed.created === 'number' && (Date.now() - parsed.created > ttlMs);
               if (!expired) {
                 cachedSessionId = parsed.id;
+                // #region agent log
+                try { fetch('http://127.0.0.1:7243/ingest/50587964-c1c6-436a-a7ce-ff2cde3c5b63',{method:'POST',headers:{'Content-Type':'application/json'},body:JSON.stringify({location:'script.js:getSessionId:local',message:'reused from localStorage',data:{sessionIdPrefix:cachedSessionId.substring(0,8)},timestamp:Date.now(),hypothesisId:'D,E'})}).catch(function(){}); } catch (e) {}
+                // #endregion
                 return cachedSessionId;
               }
             }
@@ -145,13 +161,22 @@
         }
         cachedSessionId = generateId();
         localStorage.setItem(key, JSON.stringify({ id: cachedSessionId, created: Date.now() }));
+        // #region agent log
+        try { fetch('http://127.0.0.1:7243/ingest/50587964-c1c6-436a-a7ce-ff2cde3c5b63',{method:'POST',headers:{'Content-Type':'application/json'},body:JSON.stringify({location:'script.js:getSessionId:local',message:'generated new and wrote to localStorage',data:{sessionIdPrefix:cachedSessionId.substring(0,8)},timestamp:Date.now(),hypothesisId:'C,E'})}).catch(function(){}); } catch (e) {}
+        // #endregion
       } catch (e) {
         cachedSessionId = generateId();
+        // #region agent log
+        try { fetch('http://127.0.0.1:7243/ingest/50587964-c1c6-436a-a7ce-ff2cde3c5b63',{method:'POST',headers:{'Content-Type':'application/json'},body:JSON.stringify({location:'script.js:getSessionId:local',message:'localStorage error fallback',data:{sessionIdPrefix:cachedSessionId.substring(0,8),err:String(e&&e.message)},timestamp:Date.now(),hypothesisId:'C'})}).catch(function(){}); } catch (e2) {}
+        // #endregion
       }
       return cachedSessionId;
     }
 
     // * data-storage="session": session storage (ephemeral, per-tab)
+    // #region agent log
+    try { fetch('http://127.0.0.1:7243/ingest/50587964-c1c6-436a-a7ce-ff2cde3c5b63',{method:'POST',headers:{'Content-Type':'application/json'},body:JSON.stringify({location:'script.js:getSessionId',message:'using session branch',data:{storageMode},timestamp:Date.now(),hypothesisId:'A'})}).catch(function(){}); } catch (e) {}
+    // #endregion
     try {
       cachedSessionId = sessionStorage.getItem(key);
       if (!cachedSessionId && legacyKey) {
-- 
2.49.1


From 5886cc661c92328facbd33a669e7fbdfa81ef1d5 Mon Sep 17 00:00:00 2001
From: Usman Baig <mubaig@pm.me>
Date: Wed, 11 Feb 2026 11:26:29 +0100
Subject: [PATCH 05/18] feat: implement race condition fix for session ID
 management in script.js, ensuring correct ID usage across multiple tabs

---
 public/script.js | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)

diff --git a/public/script.js b/public/script.js
index 103b820..eb56cac 100644
--- a/public/script.js
+++ b/public/script.js
@@ -160,6 +160,23 @@
           }
         }
         cachedSessionId = generateId();
+        // * Race fix: re-read before writing; if another tab wrote in the meantime, use that ID instead
+        var rawAgain = localStorage.getItem(key);
+        if (rawAgain) {
+          try {
+            var parsedAgain = JSON.parse(rawAgain);
+            if (parsedAgain && typeof parsedAgain.id === 'string') {
+              var expiredAgain = ttlMs > 0 && typeof parsedAgain.created === 'number' && (Date.now() - parsedAgain.created > ttlMs);
+              if (!expiredAgain) {
+                cachedSessionId = parsedAgain.id;
+                // #region agent log
+                try { fetch('http://127.0.0.1:7243/ingest/50587964-c1c6-436a-a7ce-ff2cde3c5b63',{method:'POST',headers:{'Content-Type':'application/json'},body:JSON.stringify({location:'script.js:getSessionId:local',message:'race fix reused other tab id',data:{sessionIdPrefix:cachedSessionId.substring(0,8)},timestamp:Date.now(),hypothesisId:'E'})}).catch(function(){}); } catch (e4) {}
+                // #endregion
+                return cachedSessionId;
+              }
+            }
+          } catch (e2) {}
+        }
         localStorage.setItem(key, JSON.stringify({ id: cachedSessionId, created: Date.now() }));
         // #region agent log
         try { fetch('http://127.0.0.1:7243/ingest/50587964-c1c6-436a-a7ce-ff2cde3c5b63',{method:'POST',headers:{'Content-Type':'application/json'},body:JSON.stringify({location:'script.js:getSessionId:local',message:'generated new and wrote to localStorage',data:{sessionIdPrefix:cachedSessionId.substring(0,8)},timestamp:Date.now(),hypothesisId:'C,E'})}).catch(function(){}); } catch (e) {}
-- 
2.49.1


From f10b79efac34a161bcb583e794f828c8dd6ed17a Mon Sep 17 00:00:00 2001
From: Usman Baig <mubaig@pm.me>
Date: Wed, 11 Feb 2026 11:32:26 +0100
Subject: [PATCH 06/18] refactor: update logging endpoints in script.js to use
 dynamic API URL for improved flexibility

---
 public/script.js | 16 ++++++++--------
 1 file changed, 8 insertions(+), 8 deletions(-)

diff --git a/public/script.js b/public/script.js
index eb56cac..6963278 100644
--- a/public/script.js
+++ b/public/script.js
@@ -28,7 +28,7 @@
   const ttlMs = ttlHours > 0 ? ttlHours * 60 * 60 * 1000 : 0;
   // #region agent log
   try {
-    fetch('http://127.0.0.1:7243/ingest/50587964-c1c6-436a-a7ce-ff2cde3c5b63',{method:'POST',headers:{'Content-Type':'application/json'},body:JSON.stringify({location:'script.js:init',message:'storage config',data:{storageMode,dataStorageAttr:script.getAttribute('data-storage'),ttlHours,ttlMs,domain},timestamp:Date.now(),hypothesisId:'A,B'})}).catch(function(){});
+    fetch(apiUrl + '/api/v1/debug-log',{method:'POST',headers:{'Content-Type':'application/json'},body:JSON.stringify({location:'script.js:init',message:'storage config',data:{storageMode,dataStorageAttr:script.getAttribute('data-storage'),ttlHours,ttlMs,domain},timestamp:Date.now(),hypothesisId:'A,B'})}).catch(function(){});
   } catch (e) {}
   // #endregion
 
@@ -126,7 +126,7 @@
   function getSessionId() {
     if (cachedSessionId) {
       // #region agent log
-      try { fetch('http://127.0.0.1:7243/ingest/50587964-c1c6-436a-a7ce-ff2cde3c5b63',{method:'POST',headers:{'Content-Type':'application/json'},body:JSON.stringify({location:'script.js:getSessionId',message:'return cached',data:{sessionIdPrefix:cachedSessionId.substring(0,8),storageMode},timestamp:Date.now(),hypothesisId:'E'})}).catch(function(){}); } catch (e) {}
+      try { fetch(apiUrl + '/api/v1/debug-log',{method:'POST',headers:{'Content-Type':'application/json'},body:JSON.stringify({location:'script.js:getSessionId',message:'return cached',data:{sessionIdPrefix:cachedSessionId.substring(0,8),storageMode},timestamp:Date.now(),hypothesisId:'E'})}).catch(function(){}); } catch (e) {}
       // #endregion
       return cachedSessionId;
     }
@@ -140,7 +140,7 @@
         // #region agent log
         var rawType = raw === null ? 'null' : typeof raw;
         var rawPrefix = raw && raw.substring ? raw.substring(0, 60) : '';
-        try { fetch('http://127.0.0.1:7243/ingest/50587964-c1c6-436a-a7ce-ff2cde3c5b63',{method:'POST',headers:{'Content-Type':'application/json'},body:JSON.stringify({location:'script.js:getSessionId:local',message:'localStorage read',data:{rawType,rawPrefix,hasRaw:!!raw},timestamp:Date.now(),hypothesisId:'C,D,E'})}).catch(function(){}); } catch (e) {}
+        try { fetch(apiUrl + '/api/v1/debug-log',{method:'POST',headers:{'Content-Type':'application/json'},body:JSON.stringify({location:'script.js:getSessionId:local',message:'localStorage read',data:{rawType,rawPrefix,hasRaw:!!raw},timestamp:Date.now(),hypothesisId:'C,D,E'})}).catch(function(){}); } catch (e) {}
         // #endregion
         if (raw) {
           try {
@@ -150,7 +150,7 @@
               if (!expired) {
                 cachedSessionId = parsed.id;
                 // #region agent log
-                try { fetch('http://127.0.0.1:7243/ingest/50587964-c1c6-436a-a7ce-ff2cde3c5b63',{method:'POST',headers:{'Content-Type':'application/json'},body:JSON.stringify({location:'script.js:getSessionId:local',message:'reused from localStorage',data:{sessionIdPrefix:cachedSessionId.substring(0,8)},timestamp:Date.now(),hypothesisId:'D,E'})}).catch(function(){}); } catch (e) {}
+                try { fetch(apiUrl + '/api/v1/debug-log',{method:'POST',headers:{'Content-Type':'application/json'},body:JSON.stringify({location:'script.js:getSessionId:local',message:'reused from localStorage',data:{sessionIdPrefix:cachedSessionId.substring(0,8)},timestamp:Date.now(),hypothesisId:'D,E'})}).catch(function(){}); } catch (e) {}
                 // #endregion
                 return cachedSessionId;
               }
@@ -170,7 +170,7 @@
               if (!expiredAgain) {
                 cachedSessionId = parsedAgain.id;
                 // #region agent log
-                try { fetch('http://127.0.0.1:7243/ingest/50587964-c1c6-436a-a7ce-ff2cde3c5b63',{method:'POST',headers:{'Content-Type':'application/json'},body:JSON.stringify({location:'script.js:getSessionId:local',message:'race fix reused other tab id',data:{sessionIdPrefix:cachedSessionId.substring(0,8)},timestamp:Date.now(),hypothesisId:'E'})}).catch(function(){}); } catch (e4) {}
+                try { fetch(apiUrl + '/api/v1/debug-log',{method:'POST',headers:{'Content-Type':'application/json'},body:JSON.stringify({location:'script.js:getSessionId:local',message:'race fix reused other tab id',data:{sessionIdPrefix:cachedSessionId.substring(0,8)},timestamp:Date.now(),hypothesisId:'E'})}).catch(function(){}); } catch (e4) {}
                 // #endregion
                 return cachedSessionId;
               }
@@ -179,12 +179,12 @@
         }
         localStorage.setItem(key, JSON.stringify({ id: cachedSessionId, created: Date.now() }));
         // #region agent log
-        try { fetch('http://127.0.0.1:7243/ingest/50587964-c1c6-436a-a7ce-ff2cde3c5b63',{method:'POST',headers:{'Content-Type':'application/json'},body:JSON.stringify({location:'script.js:getSessionId:local',message:'generated new and wrote to localStorage',data:{sessionIdPrefix:cachedSessionId.substring(0,8)},timestamp:Date.now(),hypothesisId:'C,E'})}).catch(function(){}); } catch (e) {}
+        try { fetch(apiUrl + '/api/v1/debug-log',{method:'POST',headers:{'Content-Type':'application/json'},body:JSON.stringify({location:'script.js:getSessionId:local',message:'generated new and wrote to localStorage',data:{sessionIdPrefix:cachedSessionId.substring(0,8)},timestamp:Date.now(),hypothesisId:'C,E'})}).catch(function(){}); } catch (e) {}
         // #endregion
       } catch (e) {
         cachedSessionId = generateId();
         // #region agent log
-        try { fetch('http://127.0.0.1:7243/ingest/50587964-c1c6-436a-a7ce-ff2cde3c5b63',{method:'POST',headers:{'Content-Type':'application/json'},body:JSON.stringify({location:'script.js:getSessionId:local',message:'localStorage error fallback',data:{sessionIdPrefix:cachedSessionId.substring(0,8),err:String(e&&e.message)},timestamp:Date.now(),hypothesisId:'C'})}).catch(function(){}); } catch (e2) {}
+        try { fetch(apiUrl + '/api/v1/debug-log',{method:'POST',headers:{'Content-Type':'application/json'},body:JSON.stringify({location:'script.js:getSessionId:local',message:'localStorage error fallback',data:{sessionIdPrefix:cachedSessionId.substring(0,8),err:String(e&&e.message)},timestamp:Date.now(),hypothesisId:'C'})}).catch(function(){}); } catch (e2) {}
         // #endregion
       }
       return cachedSessionId;
@@ -192,7 +192,7 @@
 
     // * data-storage="session": session storage (ephemeral, per-tab)
     // #region agent log
-    try { fetch('http://127.0.0.1:7243/ingest/50587964-c1c6-436a-a7ce-ff2cde3c5b63',{method:'POST',headers:{'Content-Type':'application/json'},body:JSON.stringify({location:'script.js:getSessionId',message:'using session branch',data:{storageMode},timestamp:Date.now(),hypothesisId:'A'})}).catch(function(){}); } catch (e) {}
+    try { fetch(apiUrl + '/api/v1/debug-log',{method:'POST',headers:{'Content-Type':'application/json'},body:JSON.stringify({location:'script.js:getSessionId',message:'using session branch',data:{storageMode},timestamp:Date.now(),hypothesisId:'A'})}).catch(function(){}); } catch (e) {}
     // #endregion
     try {
       cachedSessionId = sessionStorage.getItem(key);
-- 
2.49.1


From 03bbe84eb011f609e4850048e7c49cf6d846136e Mon Sep 17 00:00:00 2001
From: Usman Baig <mubaig@pm.me>
Date: Wed, 11 Feb 2026 13:26:28 +0100
Subject: [PATCH 07/18] fix: remove data-storage attributes from script in
 ScriptSetupBlock for simplified script integration

---
 components/sites/ScriptSetupBlock.tsx | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/components/sites/ScriptSetupBlock.tsx b/components/sites/ScriptSetupBlock.tsx
index a7a83a0..e14756e 100644
--- a/components/sites/ScriptSetupBlock.tsx
+++ b/components/sites/ScriptSetupBlock.tsx
@@ -40,7 +40,7 @@ export default function ScriptSetupBlock({
   const [scriptCopied, setScriptCopied] = useState(false)
 
   const copyScript = useCallback(() => {
-    const script = `<script defer data-domain="${site.domain}" data-api="${API_URL}" data-storage="local" data-storage-ttl="24" src="${APP_URL}/script.js"></script>`
+    const script = `<script defer data-domain="${site.domain}" data-api="${API_URL}" src="${APP_URL}/script.js"></script>`
     navigator.clipboard.writeText(script)
     setScriptCopied(true)
     toast.success('Script copied to clipboard')
@@ -87,7 +87,7 @@ export default function ScriptSetupBlock({
 
       <div className="rounded-xl bg-neutral-100 dark:bg-neutral-800 p-4 relative group">
         <code className="text-xs text-neutral-900 dark:text-white break-all font-mono block pr-10">
-          {`<script defer data-domain="${site.domain}" data-api="${API_URL}" data-storage="local" data-storage-ttl="24" src="${APP_URL}/script.js"></script>`}
+          {`<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.
-- 
2.49.1


From f423d01d7b731d14faa1cbefa3114090dcd82e85 Mon Sep 17 00:00:00 2001
From: Usman Baig <mubaig@pm.me>
Date: Wed, 11 Feb 2026 13:54:18 +0100
Subject: [PATCH 08/18] refactor: remove redundant logging code from script.js
 to streamline session ID management

---
 public/script.js | 28 ----------------------------
 1 file changed, 28 deletions(-)

diff --git a/public/script.js b/public/script.js
index 6963278..7fd4aca 100644
--- a/public/script.js
+++ b/public/script.js
@@ -26,11 +26,6 @@
   // * When storage is "local", optional TTL in hours; after TTL the ID is regenerated (e.g. 24 = one day)
   const ttlHours = storageMode === 'local' ? parseFloat(script.getAttribute('data-storage-ttl') || '24', 10) : 0;
   const ttlMs = ttlHours > 0 ? ttlHours * 60 * 60 * 1000 : 0;
-  // #region agent log
-  try {
-    fetch(apiUrl + '/api/v1/debug-log',{method:'POST',headers:{'Content-Type':'application/json'},body:JSON.stringify({location:'script.js:init',message:'storage config',data:{storageMode,dataStorageAttr:script.getAttribute('data-storage'),ttlHours,ttlMs,domain},timestamp:Date.now(),hypothesisId:'A,B'})}).catch(function(){});
-  } catch (e) {}
-  // #endregion
 
   // * Performance Monitoring (Core Web Vitals) State
   let currentEventId = null;
@@ -125,9 +120,6 @@
   // * With data-storage="local": persistent (localStorage, cross-tab), optional TTL in hours.
   function getSessionId() {
     if (cachedSessionId) {
-      // #region agent log
-      try { fetch(apiUrl + '/api/v1/debug-log',{method:'POST',headers:{'Content-Type':'application/json'},body:JSON.stringify({location:'script.js:getSessionId',message:'return cached',data:{sessionIdPrefix:cachedSessionId.substring(0,8),storageMode},timestamp:Date.now(),hypothesisId:'E'})}).catch(function(){}); } catch (e) {}
-      // #endregion
       return cachedSessionId;
     }
 
@@ -137,11 +129,6 @@
     if (storageMode === 'local') {
       try {
         const raw = localStorage.getItem(key);
-        // #region agent log
-        var rawType = raw === null ? 'null' : typeof raw;
-        var rawPrefix = raw && raw.substring ? raw.substring(0, 60) : '';
-        try { fetch(apiUrl + '/api/v1/debug-log',{method:'POST',headers:{'Content-Type':'application/json'},body:JSON.stringify({location:'script.js:getSessionId:local',message:'localStorage read',data:{rawType,rawPrefix,hasRaw:!!raw},timestamp:Date.now(),hypothesisId:'C,D,E'})}).catch(function(){}); } catch (e) {}
-        // #endregion
         if (raw) {
           try {
             const parsed = JSON.parse(raw);
@@ -149,9 +136,6 @@
               const expired = ttlMs > 0 && typeof parsed.created === 'number' && (Date.now() - parsed.created > ttlMs);
               if (!expired) {
                 cachedSessionId = parsed.id;
-                // #region agent log
-                try { fetch(apiUrl + '/api/v1/debug-log',{method:'POST',headers:{'Content-Type':'application/json'},body:JSON.stringify({location:'script.js:getSessionId:local',message:'reused from localStorage',data:{sessionIdPrefix:cachedSessionId.substring(0,8)},timestamp:Date.now(),hypothesisId:'D,E'})}).catch(function(){}); } catch (e) {}
-                // #endregion
                 return cachedSessionId;
               }
             }
@@ -169,31 +153,19 @@
               var expiredAgain = ttlMs > 0 && typeof parsedAgain.created === 'number' && (Date.now() - parsedAgain.created > ttlMs);
               if (!expiredAgain) {
                 cachedSessionId = parsedAgain.id;
-                // #region agent log
-                try { fetch(apiUrl + '/api/v1/debug-log',{method:'POST',headers:{'Content-Type':'application/json'},body:JSON.stringify({location:'script.js:getSessionId:local',message:'race fix reused other tab id',data:{sessionIdPrefix:cachedSessionId.substring(0,8)},timestamp:Date.now(),hypothesisId:'E'})}).catch(function(){}); } catch (e4) {}
-                // #endregion
                 return cachedSessionId;
               }
             }
           } catch (e2) {}
         }
         localStorage.setItem(key, JSON.stringify({ id: cachedSessionId, created: Date.now() }));
-        // #region agent log
-        try { fetch(apiUrl + '/api/v1/debug-log',{method:'POST',headers:{'Content-Type':'application/json'},body:JSON.stringify({location:'script.js:getSessionId:local',message:'generated new and wrote to localStorage',data:{sessionIdPrefix:cachedSessionId.substring(0,8)},timestamp:Date.now(),hypothesisId:'C,E'})}).catch(function(){}); } catch (e) {}
-        // #endregion
       } catch (e) {
         cachedSessionId = generateId();
-        // #region agent log
-        try { fetch(apiUrl + '/api/v1/debug-log',{method:'POST',headers:{'Content-Type':'application/json'},body:JSON.stringify({location:'script.js:getSessionId:local',message:'localStorage error fallback',data:{sessionIdPrefix:cachedSessionId.substring(0,8),err:String(e&&e.message)},timestamp:Date.now(),hypothesisId:'C'})}).catch(function(){}); } catch (e2) {}
-        // #endregion
       }
       return cachedSessionId;
     }
 
     // * data-storage="session": session storage (ephemeral, per-tab)
-    // #region agent log
-    try { fetch(apiUrl + '/api/v1/debug-log',{method:'POST',headers:{'Content-Type':'application/json'},body:JSON.stringify({location:'script.js:getSessionId',message:'using session branch',data:{storageMode},timestamp:Date.now(),hypothesisId:'A'})}).catch(function(){}); } catch (e) {}
-    // #endregion
     try {
       cachedSessionId = sessionStorage.getItem(key);
       if (!cachedSessionId && legacyKey) {
-- 
2.49.1


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 09/18] 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();
-- 
2.49.1


From 96dc5dc83d0024ab67ec7d2dddfd9070a91045be Mon Sep 17 00:00:00 2001
From: Usman Baig <mubaig@pm.me>
Date: Wed, 11 Feb 2026 14:23:21 +0100
Subject: [PATCH 10/18] docs: update CHANGELOG.md for 0.2.0-alpha release

---
 CHANGELOG.md | 12 +++++++++++-
 1 file changed, 11 insertions(+), 1 deletion(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 892cf3a..af11d0c 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -8,6 +8,15 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 - No unreleased changes yet; add items here as you work toward the next release.
 
+## [0.2.0-alpha] - 2026-02-11
+
+### Added
+
+- **Visitor ID storage: optional localStorage for cross-tab unique visitors (PULSE-51).**
+  - Default: cross-tab visitor ID in `localStorage` so the same person with multiple tabs/windows (same origin) is counted as one visitor. Optional `data-storage-ttl` attribute sets TTL in hours; after expiry the script regenerates the ID.
+  - Optional `data-storage="session"` opts out to per-tab (ephemeral) counting using `sessionStorage`, preserving the previous privacy-first, no-persistent-ID behaviour when desired.
+  - Script embed snippet and dashboard copy updated to describe the default and the opt-out. No backend or schema changes; events remain keyed by `session_id`.
+
 ## [0.1.0] - 2026-02-09
 
 ### Added
@@ -17,5 +26,6 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 ---
 
-[Unreleased]: https://github.com/ciphera-net/pulse/compare/v0.1.0...HEAD
+[Unreleased]: https://github.com/ciphera-net/pulse/compare/v0.2.0-alpha...HEAD
+[0.2.0-alpha]: https://github.com/ciphera-net/pulse/compare/v0.1.0...v0.2.0-alpha
 [0.1.0]: https://github.com/ciphera-net/pulse/releases/tag/v0.1.0
-- 
2.49.1


From d9f07f5cdea37236f32daf8fef51844247061848 Mon Sep 17 00:00:00 2001
From: Usman Baig <mubaig@pm.me>
Date: Wed, 11 Feb 2026 14:29:44 +0100
Subject: [PATCH 11/18] refactor: simplify TTL parsing in script.js and add
 comment for session ID caching behavior

---
 public/script.js | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/public/script.js b/public/script.js
index 24857c4..32949cc 100644
--- a/public/script.js
+++ b/public/script.js
@@ -24,7 +24,7 @@
   // * Visitor ID storage: "local" (default, cross-tab) or "session" (ephemeral per-tab)
   const storageMode = (script.getAttribute('data-storage') || 'local').toLowerCase() === 'session' ? 'session' : 'local';
   // * When storage is "local", optional TTL in hours; after TTL the ID is regenerated (e.g. 24 = one day)
-  const ttlHours = storageMode === 'local' ? parseFloat(script.getAttribute('data-storage-ttl') || '24', 10) : 0;
+  const ttlHours = storageMode === 'local' ? parseFloat(script.getAttribute('data-storage-ttl') || '24') : 0;
   const ttlMs = ttlHours > 0 ? ttlHours * 60 * 60 * 1000 : 0;
 
   // * Performance Monitoring (Core Web Vitals) State
@@ -172,6 +172,8 @@
             }
           } catch (e3) {}
         }
+        // * Best-effort only: another tab could write before setItem; without locks perfect sync is not achievable
+        cachedSessionId = generateId();
         localStorage.setItem(key, JSON.stringify({ id: cachedSessionId, created: Date.now() }));
       } catch (e) {
         cachedSessionId = generateId();
-- 
2.49.1


From 2d3d20f1e223769d448bb672c9132132be34712b Mon Sep 17 00:00:00 2001
From: Usman Baig <mubaig@pm.me>
Date: Wed, 11 Feb 2026 14:31:42 +0100
Subject: [PATCH 12/18] docs: update CHANGELOG.md to reflect enhancements in
 unique visitor counting and control options

---
 CHANGELOG.md | 9 ++++-----
 1 file changed, 4 insertions(+), 5 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index af11d0c..5d3dd8c 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -12,16 +12,15 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 ### Added
 
-- **Visitor ID storage: optional localStorage for cross-tab unique visitors (PULSE-51).**
-  - Default: cross-tab visitor ID in `localStorage` so the same person with multiple tabs/windows (same origin) is counted as one visitor. Optional `data-storage-ttl` attribute sets TTL in hours; after expiry the script regenerates the ID.
-  - Optional `data-storage="session"` opts out to per-tab (ephemeral) counting using `sessionStorage`, preserving the previous privacy-first, no-persistent-ID behaviour when desired.
-  - Script embed snippet and dashboard copy updated to describe the default and the opt-out. No backend or schema changes; events remain keyed by `session_id`.
+- **Smarter unique visitor counts.** If someone opens your site in several tabs or windows, they’re now counted as one visitor by default, so your stats better reflect real people.
+- **Control over how visitors are counted.** You can switch back to “one visitor per tab” (more private, no lasting identifier) by adding an option to your script embed. The dashboard shows the right snippet for both options.
+- **Optional expiry for the visitor ID.** You can set how long the cross-tab visitor ID is kept (e.g. 24 hours); after that it’s refreshed automatically.
 
 ## [0.1.0] - 2026-02-09
 
 ### Added
 
-- Initial changelog and release process (PULSE-28).
+- Initial changelog and release process.
 - Release documentation in `docs/releasing.md` and optional changelog check script.
 
 ---
-- 
2.49.1


From ce09ee0d71dcefbeccb6391cb803c1cc2f641ed6 Mon Sep 17 00:00:00 2001
From: Usman Baig <mubaig@pm.me>
Date: Wed, 11 Feb 2026 14:31:53 +0100
Subject: [PATCH 13/18] docs: update CHANGELOG.md to reflect version change to
 0.1.0-alpha

---
 CHANGELOG.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 5d3dd8c..20398d1 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -16,7 +16,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 - **Control over how visitors are counted.** You can switch back to “one visitor per tab” (more private, no lasting identifier) by adding an option to your script embed. The dashboard shows the right snippet for both options.
 - **Optional expiry for the visitor ID.** You can set how long the cross-tab visitor ID is kept (e.g. 24 hours); after that it’s refreshed automatically.
 
-## [0.1.0] - 2026-02-09
+## [0.1.0-alpha] - 2026-02-09
 
 ### Added
 
-- 
2.49.1


From 44e42475e6016940fb4c5d86313abfdd35b85656 Mon Sep 17 00:00:00 2001
From: Usman Baig <mubaig@pm.me>
Date: Wed, 11 Feb 2026 14:32:31 +0100
Subject: [PATCH 14/18] docs: remove unreleased section from CHANGELOG.md and
 update links for clarity

---
 CHANGELOG.md | 9 ---------
 1 file changed, 9 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 20398d1..1f5cd2f 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,10 +4,6 @@ All notable changes to Pulse (frontend and product) are documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and Pulse uses [Semantic Versioning](https://semver.org/spec/v2.0.0.html) with a **0.x.y** version scheme while in initial development. The leading `0` indicates that the public API and behaviour may change until we release **1.0.0**.
 
-## [Unreleased]
-
-- No unreleased changes yet; add items here as you work toward the next release.
-
 ## [0.2.0-alpha] - 2026-02-11
 
 ### Added
@@ -23,8 +19,3 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 - Initial changelog and release process.
 - Release documentation in `docs/releasing.md` and optional changelog check script.
 
----
-
-[Unreleased]: https://github.com/ciphera-net/pulse/compare/v0.2.0-alpha...HEAD
-[0.2.0-alpha]: https://github.com/ciphera-net/pulse/compare/v0.1.0...v0.2.0-alpha
-[0.1.0]: https://github.com/ciphera-net/pulse/releases/tag/v0.1.0
-- 
2.49.1


From ae2e48ce4b53097b3a9bbf018f2bb1f9da392413 Mon Sep 17 00:00:00 2001
From: Usman Baig <mubaig@pm.me>
Date: Wed, 11 Feb 2026 14:36:46 +0100
Subject: [PATCH 15/18] docs: enhance documentation in ScriptSetupBlock to
 include optional data-storage-ttl attribute for session expiry configuration

---
 components/sites/ScriptSetupBlock.tsx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/components/sites/ScriptSetupBlock.tsx b/components/sites/ScriptSetupBlock.tsx
index e12a373..b853f27 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">
-          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).
+          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). Optional: <code className="rounded px-1 bg-neutral-200 dark:bg-neutral-700">data-storage-ttl=&quot;48&quot;</code> to set expiry in hours (default: 24).
         </p>
         <button
           type="button"
-- 
2.49.1


From 10df76454ae67ed4b9a208409ddddb6ab538e717 Mon Sep 17 00:00:00 2001
From: Usman Baig <mubaig@pm.me>
Date: Wed, 11 Feb 2026 15:31:51 +0100
Subject: [PATCH 16/18] refactor: improve comment clarity in session ID caching
 logic within script.js

---
 public/script.js | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/public/script.js b/public/script.js
index 32949cc..7347a1f 100644
--- a/public/script.js
+++ b/public/script.js
@@ -172,8 +172,7 @@
             }
           } catch (e3) {}
         }
-        // * Best-effort only: another tab could write before setItem; without locks perfect sync is not achievable
-        cachedSessionId = generateId();
+        // * Best-effort only: another tab could write between here and setItem; without locks perfect sync is not achievable
         localStorage.setItem(key, JSON.stringify({ id: cachedSessionId, created: Date.now() }));
       } catch (e) {
         cachedSessionId = generateId();
-- 
2.49.1


From 069f5a606b1d7d0e657a3bd217d47b8e2bcb102a Mon Sep 17 00:00:00 2001
From: Usman Baig <mubaig@pm.me>
Date: Wed, 11 Feb 2026 15:40:23 +0100
Subject: [PATCH 17/18] docs: add unreleased section and version links to
 CHANGELOG.md for better navigation

---
 CHANGELOG.md | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 1f5cd2f..e96b62c 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -19,3 +19,8 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 - Initial changelog and release process.
 - Release documentation in `docs/releasing.md` and optional changelog check script.
 
+---
+
+[Unreleased]: https://github.com/ciphera-net/pulse/compare/v0.2.0-alpha...HEAD
+[0.2.0-alpha]: https://github.com/ciphera-net/pulse/compare/v0.1.0-alpha...v0.2.0-alpha
+[0.1.0-alpha]: https://github.com/ciphera-net/pulse/releases/tag/v0.1.0-alpha
-- 
2.49.1


From 4a8f627a5c7905ae1d46687f76670691728cb6d0 Mon Sep 17 00:00:00 2001
From: Usman Baig <mubaig@pm.me>
Date: Wed, 11 Feb 2026 15:52:30 +0100
Subject: [PATCH 18/18] refactor: enhance session ID caching logic to handle
 legacy string format and improve expiration checks

---
 public/script.js | 32 ++++++++++++++++++++++++++------
 1 file changed, 26 insertions(+), 6 deletions(-)

diff --git a/public/script.js b/public/script.js
index 7347a1f..d360ce7 100644
--- a/public/script.js
+++ b/public/script.js
@@ -133,14 +133,22 @@
           try {
             const parsed = JSON.parse(raw);
             if (parsed && typeof parsed.id === 'string') {
-              const expired = ttlMs > 0 && typeof parsed.created === 'number' && (Date.now() - parsed.created > ttlMs);
+              const hasValidCreated = typeof parsed.created === 'number';
+              const expired = ttlMs > 0 && (!hasValidCreated || (Date.now() - parsed.created > ttlMs));
               if (!expired) {
                 cachedSessionId = parsed.id;
                 return cachedSessionId;
               }
             }
           } catch (e) {
-            // * Invalid JSON or old string format: treat as expired and regenerate
+            // * Invalid JSON: migrate legacy plain-string ID to { id, created } format
+            if (typeof raw === 'string' && raw.trim().length > 0) {
+              cachedSessionId = raw.trim();
+              try {
+                localStorage.setItem(key, JSON.stringify({ id: cachedSessionId, created: Date.now() }));
+              } catch (e2) {}
+              return cachedSessionId;
+            }
           }
         }
         cachedSessionId = generateId();
@@ -150,13 +158,19 @@
           try {
             var parsedAgain = JSON.parse(rawAgain);
             if (parsedAgain && typeof parsedAgain.id === 'string') {
-              var expiredAgain = ttlMs > 0 && typeof parsedAgain.created === 'number' && (Date.now() - parsedAgain.created > ttlMs);
+              var hasValidCreatedAgain = typeof parsedAgain.created === 'number';
+              var expiredAgain = ttlMs > 0 && (!hasValidCreatedAgain || (Date.now() - parsedAgain.created > ttlMs));
               if (!expiredAgain) {
                 cachedSessionId = parsedAgain.id;
                 return cachedSessionId;
               }
             }
-          } catch (e2) {}
+          } catch (e2) {
+            if (typeof rawAgain === 'string' && rawAgain.trim().length > 0) {
+              cachedSessionId = rawAgain.trim();
+              return cachedSessionId;
+            }
+          }
         }
         // * Final re-read immediately before write to avoid overwriting a fresher ID from another tab
         var rawBeforeWrite = localStorage.getItem(key);
@@ -164,13 +178,19 @@
           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);
+              var hasValidCreatedBefore = typeof parsedBefore.created === 'number';
+              var expBefore = ttlMs > 0 && (!hasValidCreatedBefore || (Date.now() - parsedBefore.created > ttlMs));
               if (!expBefore) {
                 cachedSessionId = parsedBefore.id;
                 return cachedSessionId;
               }
             }
-          } catch (e3) {}
+          } catch (e3) {
+            if (typeof rawBeforeWrite === 'string' && rawBeforeWrite.trim().length > 0) {
+              cachedSessionId = rawBeforeWrite.trim();
+              return cachedSessionId;
+            }
+          }
         }
         // * Best-effort only: another tab could write between here and setItem; without locks perfect sync is not achievable
         localStorage.setItem(key, JSON.stringify({ id: cachedSessionId, created: Date.now() }));
-- 
2.49.1