@groundcover/browser 0.0.77-rc.0 → 0.0.77-rc.1

package/README.md

@@ -140,7 +140,16 @@ export interface SDKOptions {
 }
 ```
 
-`sessionMaxDuration` caps wall-clock session length (default 4 hours, must be between 1 minute and 8 hours). The cap is enforced lazily: when the next user/business event is produced after the cap has elapsed, the SDK flushes pending events under the current session id, generates a fresh id, and resumes replay recording if it had been active. A dormant tab that produces no further events keeps its session id (session replay batches don't count, so a backgrounded recording won't spawn empty sessions). The flush is best-effort and the rotation always proceeds regardless of delivery success. Values outside that range or otherwise invalid fall back to the default with a `console.warn`.
+`sessionMaxDuration` sets a **target** maximum wall-clock session length (default 4 hours, must be between 1 minute and 8 hours).
+
+It is enforced **lazily, on activity — not by a background timer**, so it is **not a hard upper bound**. Once the cap has elapsed, the *next* user/business event (click, navigation, log, custom, network, exception, …) flushes pending events under the current session id, generates a fresh id, and resumes replay recording if it had been active.
+
+Because rotation is activity-gated, a session that goes idle keeps its id past the cap until the next qualifying event:
+
+- A dormant or backgrounded tab that produces no further events stays on the same session id — by design, so the SDK doesn't mint "phantom" sessions for tabs nobody is using.
+- **Session-replay batches don't count as activity** (rrweb emits a snapshot heartbeat every ~30s regardless of interaction), so a tab that's only recording replay won't rotate on that alone. Such a tab is ultimately bounded by the 30-minute replay-inactivity stop, not by this cap.
+
+The flush is best-effort and the rotation always proceeds regardless of delivery success. Values outside the allowed range or otherwise invalid fall back to the default with a `console.warn`.
 
 You can pass the values by calling the init function:
 

package/dist/index.d.mts

@@ -205,16 +205,30 @@ interface SDKOptions {
         blockedSelectors?: string[];
     };
     /**
-     * Maximum wall-clock duration of a session, in milliseconds. The cap is
-     * enforced lazily: the next user/business event after the cap has elapsed
-     * flushes buffered events under the current session id, then generates a
-     * fresh session id and restarts replay recording if it was active. Session
-     * replay batches never trigger this on their own. The flush is best-effort
-     * and the rotation always proceeds — it does not wait for or depend on
-     * successful delivery, so if that network request fails the batch may be
-     * lost while the new session id still takes effect. Defaults to 4 hours when
-     * omitted; must be between 1 minute and 8 hours. Values outside that range
-     * or otherwise invalid fall back to the 4-hour default with a `console.warn`.
+     * Target maximum wall-clock duration of a session, in milliseconds.
+     *
+     * Enforced LAZILY, on activity — not by a background timer. Once the cap has
+     * elapsed, the next user/business event (click, navigation, log, custom,
+     * network, exception, …) flushes buffered events under the current session
+     * id, then mints a fresh session id and restarts replay recording if it was
+     * active.
+     *
+     * Because it is activity-gated, this is NOT a hard upper bound: a session
+     * only rotates when the next qualifying event arrives. An idle or
+     * backgrounded tab that produces no such events — including one that is only
+     * emitting session-replay heartbeats, which never trigger rotation on their
+     * own — keeps the same session id past the cap until activity resumes. This
+     * is deliberate: it avoids minting "phantom" sessions for dormant tabs. (An
+     * idle tab with replay on is ultimately bounded by the 30-minute
+     * replay-inactivity stop, not by this cap.)
+     *
+     * The flush is best-effort and the rotation always proceeds — it does not
+     * wait for or depend on successful delivery, so if that network request
+     * fails the batch may be lost while the new session id still takes effect.
+     *
+     * Defaults to 4 hours when omitted; must be between 1 minute and 8 hours.
+     * Values outside that range or otherwise invalid fall back to the 4-hour
+     * default with a `console.warn`.
      */
     sessionMaxDuration?: number;
 }

package/dist/index.d.ts

@@ -205,16 +205,30 @@ interface SDKOptions {
         blockedSelectors?: string[];
     };
     /**
-     * Maximum wall-clock duration of a session, in milliseconds. The cap is
-     * enforced lazily: the next user/business event after the cap has elapsed
-     * flushes buffered events under the current session id, then generates a
-     * fresh session id and restarts replay recording if it was active. Session
-     * replay batches never trigger this on their own. The flush is best-effort
-     * and the rotation always proceeds — it does not wait for or depend on
-     * successful delivery, so if that network request fails the batch may be
-     * lost while the new session id still takes effect. Defaults to 4 hours when
-     * omitted; must be between 1 minute and 8 hours. Values outside that range
-     * or otherwise invalid fall back to the 4-hour default with a `console.warn`.
+     * Target maximum wall-clock duration of a session, in milliseconds.
+     *
+     * Enforced LAZILY, on activity — not by a background timer. Once the cap has
+     * elapsed, the next user/business event (click, navigation, log, custom,
+     * network, exception, …) flushes buffered events under the current session
+     * id, then mints a fresh session id and restarts replay recording if it was
+     * active.
+     *
+     * Because it is activity-gated, this is NOT a hard upper bound: a session
+     * only rotates when the next qualifying event arrives. An idle or
+     * backgrounded tab that produces no such events — including one that is only
+     * emitting session-replay heartbeats, which never trigger rotation on their
+     * own — keeps the same session id past the cap until activity resumes. This
+     * is deliberate: it avoids minting "phantom" sessions for dormant tabs. (An
+     * idle tab with replay on is ultimately bounded by the 30-minute
+     * replay-inactivity stop, not by this cap.)
+     *
+     * The flush is best-effort and the rotation always proceeds — it does not
+     * wait for or depend on successful delivery, so if that network request
+     * fails the batch may be lost while the new session id still takes effect.
+     *
+     * Defaults to 4 hours when omitted; must be between 1 minute and 8 hours.
+     * Values outside that range or otherwise invalid fall back to the 4-hour
+     * default with a `console.warn`.
      */
     sessionMaxDuration?: number;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@groundcover/browser",
-  "version": "0.0.77-rc.0",
+  "version": "0.0.77-rc.1",
   "description": "groundcover browser SDK",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -66,4 +66,4 @@
       "limit": "82 kB"
     }
   ]
-}
+}