@lunardinos/browser 0.2.3 → 0.2.5

package/dist/src/recorder-core.d.ts

@@ -11,6 +11,13 @@ interface RecorderConfig {
     batchInterval?: number;
     /** Initial persistence mode: 'cookie' (default) or 'cookieless'. Can be changed at runtime via setPersistence(). */
     defaultPersistence?: PersistenceMode;
+    /**
+     * BCP-47 language the app renders in (e.g. "de"). Static fallback used when a page
+     * event doesn't carry its own locale and `<html lang>` isn't set. Prefer passing the
+     * current locale per navigation via the framework SDK's page metadata, since the app
+     * knows the shown language and it can change at runtime.
+     */
+    locale?: string;
 }
 interface PageEventPayload {
     href: string;
@@ -18,6 +25,8 @@ interface PageEventPayload {
     routePattern: string | null;
     params: Record<string, string> | null;
     referrer?: string | null;
+    /** BCP-47 language this page was rendered in (e.g. "de"). The app knows this. */
+    locale?: string | null;
 }
 export interface IdentifyPayload {
     user: {

package/dist/src/recorder-core.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"recorder-core.d.ts","sourceRoot":"","sources":["../../src/recorder-core.ts"],"names":[],"mappings":"AACA,OAAO,EAA8C,KAAK,eAAe,EAAE,MAAM,eAAe,CAAA;AAEhG,YAAY,EAAE,eAAe,EAAE,MAAM,eAAe,CAAA;AAIpD,UAAU,cAAc;IACtB,iCAAiC;IACjC,MAAM,EAAE,MAAM,CAAA;IACd,qEAAqE;IACrE,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,kEAAkE;IAClE,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IACtC,6CAA6C;IAC7C,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,oHAAoH;IACpH,kBAAkB,CAAC,EAAE,eAAe,CAAA;CACrC;AA4BD,UAAU,gBAAgB;IACxB,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,EAAE,MAAM,CAAA;IACb,YAAY,EAAE,MAAM,GAAG,IAAI,CAAA;IAC3B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,CAAA;IACrC,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CACzB;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE;QACJ,EAAE,EAAE,MAAM,CAAA;QACV,KAAK,CAAC,EAAE,MAAM,CAAA;QACd,IAAI,CAAC,EAAE,MAAM,CAAA;QACb,IAAI,CAAC,EAAE,MAAM,CAAA;QACb,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;KACvB,CAAA;IACD,OAAO,CAAC,EAAE;QACR,EAAE,EAAE,MAAM,CAAA;QACV,IAAI,CAAC,EAAE,MAAM,CAAA;QACb,SAAS,CAAC,EAAE,OAAO,CAAA;QACnB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;KACvB,CAAA;IACD,IAAI,CAAC,EAAE;QACL,EAAE,EAAE,MAAM,CAAA;QACV,IAAI,CAAC,EAAE,MAAM,CAAA;QACb,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;KACvB,CAAA;CACF;AAuCD,MAAM,WAAW,YAAY;IAC3B,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,8FAA8F;IAC9F,YAAY,CAAC,EAAE,gBAAgB,CAAA;CAChC;AAED,MAAM,WAAW,QAAQ;IACvB,KAAK,EAAE,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,YAAY,KAAK,MAAM,CAAA;IAClD,IAAI,EAAE,MAAM,IAAI,CAAA;IAChB,+FAA+F;IAC/F,KAAK,EAAE,CAAC,OAAO,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,OAAO,CAAA;KAAE,KAAK,IAAI,CAAA;IAC/C,YAAY,EAAE,MAAM,MAAM,GAAG,IAAI,CAAA;IACjC,YAAY,EAAE,MAAM,MAAM,GAAG,IAAI,CAAA;IACjC,WAAW,EAAE,MAAM,OAAO,CAAA;IAC1B,iFAAiF;IACjF,aAAa,EAAE,CAAC,OAAO,EAAE,gBAAgB,KAAK,IAAI,CAAA;IAClD,4EAA4E;IAC5E,QAAQ,EAAE,CAAC,OAAO,EAAE,eAAe,KAAK,IAAI,CAAA;IAC5C,2EAA2E;IAC3E,cAAc,EAAE,CAAC,IAAI,EAAE,eAAe,KAAK,IAAI,CAAA;CAChD;AAED;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,cAAc,GAAG,QAAQ,CA+bzE"}
+{"version":3,"file":"recorder-core.d.ts","sourceRoot":"","sources":["../../src/recorder-core.ts"],"names":[],"mappings":"AACA,OAAO,EAA8C,KAAK,eAAe,EAAE,MAAM,eAAe,CAAA;AAShG,YAAY,EAAE,eAAe,EAAE,MAAM,eAAe,CAAA;AAuBpD,UAAU,cAAc;IACtB,iCAAiC;IACjC,MAAM,EAAE,MAAM,CAAA;IACd,qEAAqE;IACrE,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,kEAAkE;IAClE,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IACtC,6CAA6C;IAC7C,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,oHAAoH;IACpH,kBAAkB,CAAC,EAAE,eAAe,CAAA;IACpC;;;;;OAKG;IACH,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB;AA4BD,UAAU,gBAAgB;IACxB,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,EAAE,MAAM,CAAA;IACb,YAAY,EAAE,MAAM,GAAG,IAAI,CAAA;IAC3B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,CAAA;IACrC,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACxB,iFAAiF;IACjF,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CACvB;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE;QACJ,EAAE,EAAE,MAAM,CAAA;QACV,KAAK,CAAC,EAAE,MAAM,CAAA;QACd,IAAI,CAAC,EAAE,MAAM,CAAA;QACb,IAAI,CAAC,EAAE,MAAM,CAAA;QACb,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;KACvB,CAAA;IACD,OAAO,CAAC,EAAE;QACR,EAAE,EAAE,MAAM,CAAA;QACV,IAAI,CAAC,EAAE,MAAM,CAAA;QACb,SAAS,CAAC,EAAE,OAAO,CAAA;QACnB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;KACvB,CAAA;IACD,IAAI,CAAC,EAAE;QACL,EAAE,EAAE,MAAM,CAAA;QACV,IAAI,CAAC,EAAE,MAAM,CAAA;QACb,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;KACvB,CAAA;CACF;AAuED,MAAM,WAAW,YAAY;IAC3B,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,8FAA8F;IAC9F,YAAY,CAAC,EAAE,gBAAgB,CAAA;CAChC;AAED,MAAM,WAAW,QAAQ;IACvB,KAAK,EAAE,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,YAAY,KAAK,MAAM,CAAA;IAClD,IAAI,EAAE,MAAM,IAAI,CAAA;IAChB,+FAA+F;IAC/F,KAAK,EAAE,CAAC,OAAO,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,OAAO,CAAA;KAAE,KAAK,IAAI,CAAA;IAC/C,YAAY,EAAE,MAAM,MAAM,GAAG,IAAI,CAAA;IACjC,YAAY,EAAE,MAAM,MAAM,GAAG,IAAI,CAAA;IACjC,WAAW,EAAE,MAAM,OAAO,CAAA;IAC1B,iFAAiF;IACjF,aAAa,EAAE,CAAC,OAAO,EAAE,gBAAgB,KAAK,IAAI,CAAA;IAClD,4EAA4E;IAC5E,QAAQ,EAAE,CAAC,OAAO,EAAE,eAAe,KAAK,IAAI,CAAA;IAC5C,2EAA2E;IAC3E,cAAc,EAAE,CAAC,IAAI,EAAE,eAAe,KAAK,IAAI,CAAA;CAChD;AAED;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,cAAc,GAAG,QAAQ,CAmjBzE"}

package/dist/src/recorder-core.js

@@ -1,6 +1,24 @@
-import record from "@lunardinos/rrweb-record";
+import record, {} from "@lunardinos/rrweb-record";
 import { createPersistence } from "./persistence";
+import { isNavigation, isUserActivity, SESSION_TIMEOUT_MS, sessionExpired, storedSessionUsable, } from "./session-lifecycle";
 const DEFAULT_ENDPOINT = "https://ingest.lunardinos.com";
+/** Timestamp of the last user activity, alongside the session id in sessionStorage. */
+const SESSION_ACTIVITY_KEY = "__ld_sid_at";
+/**
+ * How often to force a full snapshot.
+ *
+ * These are the replay's keyframes: the player can only start rendering from a
+ * snapshot, so seeking to an arbitrary point costs replaying every mutation
+ * since the preceding one. That makes this interval the ceiling on seek latency
+ * — at five minutes, jumping around a long recording meant fast-forwarding
+ * through up to five minutes of DOM mutations per jump.
+ *
+ * The tradeoff is upload size: each snapshot is the whole DOM. Stylesheets and
+ * images are content-addressed and deduplicated across the session, so the
+ * marginal cost of an extra snapshot is mostly the node tree, which compresses
+ * well — worth paying for a 5x cut in seek latency.
+ */
+const FULL_SNAPSHOT_INTERVAL_MS = 60 * 1000;
 /** Compress a string via the CompressionStream API (gzip). Returns null if unavailable or on error. */
 async function gzipCompress(input) {
     try {
@@ -37,6 +55,38 @@ function truncateText(text) {
         return null;
     return text.length > 40 ? `${text.slice(0, 37)}...` : text;
 }
+// Hard filter for auth tokens / secrets apps leak into URLs — notably Supabase,
+// which puts `#access_token=…&refresh_token=…` in the location hash after an OAuth
+// callback. Strip them here so live tokens never leave the browser. The server
+// re-applies the same filter on ingest (defense-in-depth). Kept in sync with
+// packages/shared/src/redact-url.ts (the SDK bundle is standalone, so it can't
+// import the shared server module).
+const AUTH_URL_KEYS = "access[_-]?token|refresh[_-]?token|provider[_-]?token|provider[_-]?refresh[_-]?token|id[_-]?token|token|token[_-]?type|expires[_-]?at|expires[_-]?in|code|client[_-]?secret|session[_-]?token|jwt|api[_-]?key|password|secret";
+const AUTH_PAIR = new RegExp(`\\b(${AUTH_URL_KEYS})=[^&#\\s"']*`, "gi");
+const AUTH_FRAG = new RegExp(`#[^#\\s]*\\b(?:${AUTH_URL_KEYS})=`, "i");
+function redactAuthFromUrl(value) {
+    if (value == null)
+        return value;
+    if (value.indexOf("=") === -1)
+        return value;
+    let v = value;
+    if (AUTH_FRAG.test(v)) {
+        const h = v.indexOf("#");
+        if (h >= 0)
+            v = v.slice(0, h);
+    }
+    return v.replace(AUTH_PAIR, (m) => `${m.slice(0, m.indexOf("=") + 1)}REDACTED`);
+}
+/** Read the page's rendered language from `<html lang>`, lowercased, or null. */
+function readHtmlLang() {
+    try {
+        const lang = document.documentElement.getAttribute("lang");
+        return lang?.trim() ? lang.trim().toLowerCase() : null;
+    }
+    catch {
+        return null;
+    }
+}
 /** Extract UTM parameters from the current URL. */
 function extractUtmParams() {
     const params = new URLSearchParams(window.location.search);
@@ -57,6 +107,13 @@ function extractUtmParams() {
  */
 export function createLunarDinosRecorder(config) {
     const { apiKey, endpoint = DEFAULT_ENDPOINT, rrwebOptions = {}, batchInterval = 2000 } = config;
+    const configLocale = config.locale ?? null;
+    /**
+     * Resolve the locale to stamp on a page event: an explicit per-page value wins
+     * (the app told us), then the live `<html lang>` (authoritative and updates on
+     * navigation), then the static config default.
+     */
+    const resolveLocale = (explicit) => explicit ?? readHtmlLang() ?? configLocale;
     // Always inline images so they display correctly in replay (the replay
     // iframe is on a different origin and can't fetch original URLs).
     const defaultRrwebOptions = {
@@ -85,7 +142,18 @@ export function createLunarDinosRecorder(config) {
             method: "POST",
             headers: reqHeaders,
             body,
-        }).catch(() => { });
+        })
+            .then((res) => {
+            // Fire-and-forget by design (recording must never block the page), but a
+            // failed delivery should at least be visible in devtools/error monitoring
+            // instead of vanishing — this batch's events are gone either way.
+            if (!res.ok) {
+                console.error(`lunardinos: ingest request failed with status ${res.status}`);
+            }
+        })
+            .catch(() => {
+            console.error("lunardinos: ingest request failed (network error)");
+        });
     }
     /** Send via navigator.sendBeacon — reliable during page unload, no custom headers. */
     function sendViaBeacon(json) {
@@ -120,7 +188,17 @@ export function createLunarDinosRecorder(config) {
     let visitorId = null;
     let stopFn = null;
     let intervalId = null;
+    // Periodic full-snapshot ("checkout") timer. Bounds segment size for long
+    // single-page sessions: each snapshot becomes an independently-replayable
+    // segment boundary, so the player never has to load one giant blob.
+    let checkoutIntervalId = null;
     let recording = false;
+    /** Last user activity, for {@link SESSION_TIMEOUT_MS}. */
+    let lastActivityAt = 0;
+    /** Set while rotating, since taking the new session's snapshot re-enters emit. */
+    let rotating = false;
+    /** The page the app last reported, so a rotated session opens on it. */
+    let currentPage = {};
     // Click enrichment state
     let pendingClickContext = null;
     // Input enrichment state
@@ -185,11 +263,55 @@ export function createLunarDinosRecorder(config) {
             truncateText(getDirectText(clicked)) ??
             clicked.querySelector("[aria-label]")?.getAttribute("aria-label") ??
             null;
-        const href = tag === "a"
+        const href = redactAuthFromUrl(tag === "a"
             ? clicked.getAttribute("href")
-            : (clicked.closest("a")?.getAttribute("href") ?? null);
+            : (clicked.closest("a")?.getAttribute("href") ?? null));
         pendingClickContext = { clickTag: tag, clickRole: role, clickName: name, clickHref: href };
     }
+    /**
+     * End the current session and open a new one.
+     *
+     * Order matters: pending events belong to the session that produced them, so
+     * they go out first, and the new session opens on a navigation and a full
+     * snapshot — without one it starts mid-stream against a DOM the player has
+     * never seen and can't be replayed at all, and has no landing page.
+     *
+     * `snapshot: false` when a navigation triggered the rotation: its own
+     * snapshot follows and opens the new session.
+     */
+    function rotateSession(snapshot) {
+        if (rotating)
+            return;
+        rotating = true;
+        try {
+            flush();
+            sessionId = crypto.randomUUID();
+            persistence.setSessionId(sessionId);
+            if (typeof sessionStorage !== "undefined") {
+                sessionStorage.setItem("__ld_sid", sessionId);
+            }
+            lastActivityAt = Date.now();
+            markActivity();
+            if (snapshot) {
+                try {
+                    record.takeNavigationSnapshot(currentPage);
+                }
+                catch {
+                    // Recording already stopped; the next start() will snapshot anyway.
+                }
+            }
+        }
+        finally {
+            rotating = false;
+        }
+    }
+    /** Persist the activity clock so a reload in the same tab can honour it. */
+    function markActivity() {
+        lastActivityAt = Date.now();
+        if (typeof sessionStorage !== "undefined") {
+            sessionStorage.setItem(SESSION_ACTIVITY_KEY, String(lastActivityAt));
+        }
+    }
     function flush(options) {
         if (events.length === 0 || !sessionId)
             return;
@@ -232,16 +354,24 @@ export function createLunarDinosRecorder(config) {
         }
         flush();
     }
+    /** What a navigation reports about a page, with auth tokens stripped from its URL. */
+    function pageMetadata(payload) {
+        return {
+            href: redactAuthFromUrl(payload.href) ?? payload.href,
+            title: payload.title,
+            routePattern: payload.routePattern ?? undefined,
+            params: payload.params,
+            locale: resolveLocale(payload.locale),
+        };
+    }
     function emitPageEvent(payload) {
         if (!recording)
             return;
+        currentPage = pageMetadata(payload);
         try {
-            // Single Pageview event carries both DOM snapshot and route metadata
-            record.takePageviewSnapshot({
-                href: payload.href,
-                title: payload.title,
-                routePattern: payload.routePattern ?? undefined,
-                params: payload.params,
+            // The navigation event, then Meta + FullSnapshot of the new page
+            record.takeNavigationSnapshot({
+                ...currentPage,
                 referrer: payload.referrer ?? externalReferrer(),
             });
         }
@@ -324,7 +454,15 @@ export function createLunarDinosRecorder(config) {
         let isNewSession = false;
         if (persistence.mode === "cookie") {
             const persistedSession = persistence.getSessionId();
-            const storedSession = typeof sessionStorage !== "undefined" ? sessionStorage.getItem(SESSION_STORAGE_KEY) : null;
+            // sessionStorage outlives the session cookie — it's scoped to the tab, not
+            // to 30 minutes — so reusing it unconditionally resurrected sessions the
+            // cookie had already expired. Only honour it while it's still fresh.
+            const storedAt = typeof sessionStorage !== "undefined"
+                ? Number(sessionStorage.getItem(SESSION_ACTIVITY_KEY))
+                : Number.NaN;
+            const storedSession = storedSessionUsable(storedAt, Date.now()) && typeof sessionStorage !== "undefined"
+                ? sessionStorage.getItem(SESSION_STORAGE_KEY)
+                : null;
             isNewSession = !persistedSession && !storedSession;
             sessionId = persistedSession || storedSession || existingSessionId || crypto.randomUUID();
             persistence.setSessionId(sessionId);
@@ -345,6 +483,7 @@ export function createLunarDinosRecorder(config) {
         }
         events = [];
         recording = true;
+        markActivity();
         // Listen for clicks/inputs in capture phase to grab context before rrweb sees it
         document.addEventListener("click", captureClickContext, true);
         document.addEventListener("input", captureInputContext, true);
@@ -352,20 +491,24 @@ export function createLunarDinosRecorder(config) {
         document.addEventListener("submit", captureSubmit, true);
         window.addEventListener("error", captureError);
         window.addEventListener("unhandledrejection", captureRejection);
+        currentPage = startOpts.pageMetadata ? pageMetadata(startOpts.pageMetadata) : {};
         stopFn = record({
             ...defaultRrwebOptions,
             ...rrwebOptions,
             initialPageMetadata: startOpts.pageMetadata
-                ? {
-                    href: startOpts.pageMetadata.href,
-                    title: startOpts.pageMetadata.title,
-                    routePattern: startOpts.pageMetadata.routePattern ?? undefined,
-                    params: startOpts.pageMetadata.params,
-                    referrer: startOpts.pageMetadata.referrer ?? undefined,
-                }
+                ? { ...currentPage, referrer: startOpts.pageMetadata.referrer ?? undefined }
                 : undefined,
             emit(event) {
                 const ev = event;
+                // A navigation, or anything a human did, keeps the session alive; if the
+                // gap since the last one is too long this is a new sitting, so close the
+                // old session before the event is recorded against it.
+                if (isUserActivity(ev) && !rotating) {
+                    if (sessionExpired(lastActivityAt, Date.now()))
+                        rotateSession(!isNavigation(ev));
+                    else
+                        markActivity();
+                }
                 // Attach click context to rrweb click events
                 if (ev.type === 3 && ev.data?.source === 2 && ev.data?.type === 2 && pendingClickContext) {
                     const d = ev.data;
@@ -391,10 +534,20 @@ export function createLunarDinosRecorder(config) {
         if (persistence.mode === "cookieless" || isNewSession) {
             emitSessionMeta();
         }
-        // Flush immediately so the pageview snapshot (which can exceed sendBeacon's
+        // Flush immediately so the first snapshot (which can exceed sendBeacon's
         // ~64 KB limit) is delivered via regular fetch before the user navigates away.
         flush();
         intervalId = setInterval(flush, batchInterval);
+        // Take a periodic full snapshot so long single-page sessions are split into
+        // bounded, independently-replayable segments (matches PostHog's 5-min cadence).
+        checkoutIntervalId = setInterval(() => {
+            try {
+                record.takeFullSnapshot(true);
+            }
+            catch {
+                /* not recording / mid-teardown */
+            }
+        }, FULL_SNAPSHOT_INTERVAL_MS);
         return sessionId;
     }
     function stop() {
@@ -417,6 +570,10 @@ export function createLunarDinosRecorder(config) {
             clearInterval(intervalId);
             intervalId = null;
         }
+        if (checkoutIntervalId) {
+            clearInterval(checkoutIntervalId);
+            checkoutIntervalId = null;
+        }
         stopFn?.();
         stopFn = null;
         recording = false;

package/dist/src/recorder.browser.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=recorder.browser.test.d.ts.map

package/dist/src/recorder.browser.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recorder.browser.test.d.ts","sourceRoot":"","sources":["../../src/recorder.browser.test.ts"],"names":[],"mappings":""}

package/dist/src/recorder.browser.test.js

@@ -0,0 +1,144 @@
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { chromium } from "playwright";
+import { buildRecorderBundle } from "./testing/recorder-bundle";
+/**
+ * What the recorder uploads around navigations, keyframes and session
+ * rotation, captured off the wire from the production recorder in Chromium on
+ * a fake clock.
+ *
+ * A navigation is a Custom "navigation" event followed by Meta + FullSnapshot;
+ * a keyframe is Meta + FullSnapshot alone. Keyframes are the recorder's own
+ * doing, so they must not keep an idle session alive, and a session rotated
+ * after inactivity must open on a navigation so it has a landing page.
+ */
+const PAGE = `<!DOCTYPE html><html lang="de"><head><title>App</title></head><body>
+<div id="app"><h1>Shifts</h1><button id="b">Apply</button></div>
+<script src="/recorder.js"></script></body></html>`;
+let browser;
+let bundle;
+beforeAll(async () => {
+    bundle = await buildRecorderBundle();
+    browser = await chromium.launch();
+});
+afterAll(() => browser.close());
+async function openPage() {
+    const uploads = [];
+    const page = await browser.newPage();
+    await page.route("https://app.test/**", (route) => {
+        const { pathname } = new URL(route.request().url());
+        if (pathname === "/recorder.js")
+            return route.fulfill({ contentType: "application/javascript", body: bundle });
+        return route.fulfill({ contentType: "text/html", body: PAGE });
+    });
+    await page.route("https://ingest.test/**", (route) => {
+        const req = route.request();
+        const body = new Uint8Array(req.postDataBuffer() ?? []);
+        const json = req.headers()["content-encoding"] === "gzip" ? Bun.gunzipSync(body) : body;
+        uploads.push(JSON.parse(new TextDecoder().decode(json)));
+        return route.fulfill({ status: 200, body: "{}" });
+    });
+    await page.clock.install({ time: new Date("2026-01-01T10:00:00Z") });
+    await page.goto("https://app.test/shifts?access_token=secret");
+    await page.evaluate(() => {
+        const g = globalThis;
+        g.__recorder = g.LunarDinos.createLunarDinosRecorder({
+            apiKey: "k",
+            endpoint: "https://ingest.test",
+        });
+        g.__recorder.start({
+            pageMetadata: {
+                href: location.href,
+                title: "App",
+                routePattern: "/shifts",
+                params: null,
+            },
+        });
+    });
+    await settle(page);
+    return { page, uploads };
+}
+/** Run the fake clock forward, then let the async gzip + fetch land on the real one. */
+async function settle(page, ms = 2_100) {
+    await page.clock.runFor(ms);
+    await new Promise((r) => setTimeout(r, 150));
+}
+const all = (uploads) => uploads.flatMap((u) => u.events);
+const kinds = (events) => events
+    .filter((e) => e.type !== 3 && e.type !== 0 && e.type !== 1)
+    .map((e) => (e.type === 5 ? `5:${e.data.tag}` : String(e.type)));
+describe("recorder uploads", () => {
+    test("a recording opens on a navigation with the page metadata, then Meta + FullSnapshot", async () => {
+        const { page, uploads } = await openPage();
+        const events = all(uploads);
+        expect(kinds(events).slice(0, 3)).toEqual(["5:navigation", "4", "2"]);
+        const [nav, meta] = events.filter((e) => e.type === 5 || e.type === 4);
+        expect(nav.data.payload).toMatchObject({
+            href: "https://app.test/shifts?access_token=REDACTED",
+            title: "App",
+            routePattern: "/shifts",
+            params: null,
+            locale: "de",
+        });
+        // Tokens are stripped from the snapshot's href too, not only the page view's.
+        expect(meta.data.href).toBe("https://app.test/shifts?access_token=REDACTED");
+        expect(events.map((e) => e.type)).not.toContain(7);
+        await page.close();
+    });
+    test("an SPA navigation is a navigation, then Meta + FullSnapshot", async () => {
+        const { page, uploads } = await openPage();
+        const before = all(uploads).length;
+        await page.evaluate(() => {
+            document.getElementById("app").innerHTML = "<h1>Profile</h1>";
+            globalThis.__recorder.emitPageEvent({
+                href: "https://app.test/profile",
+                title: "Profile",
+                routePattern: "/profile",
+                params: null,
+            });
+        });
+        await settle(page);
+        const events = all(uploads).slice(before);
+        expect(kinds(events)).toEqual(["5:navigation", "4", "2"]);
+        expect(events[0].data.payload.routePattern).toBe("/profile");
+        await page.close();
+    });
+    test("a periodic keyframe is Meta + FullSnapshot without a navigation", async () => {
+        const { page, uploads } = await openPage();
+        const before = all(uploads).length;
+        await settle(page, 60_000);
+        expect(kinds(all(uploads).slice(before))).toEqual(["4", "2"]);
+        await page.close();
+    });
+    test("keyframes don't keep an idle session alive; it rotates onto a navigation", async () => {
+        const { page, uploads } = await openPage();
+        const first = uploads[0].sessionId;
+        // 31 idle minutes: only keyframes are recorded meanwhile.
+        await settle(page, 31 * 60_000);
+        expect(new Set(uploads.map((u) => u.sessionId))).toEqual(new Set([first]));
+        await page.click("#b");
+        await settle(page);
+        const next = uploads.filter((u) => u.sessionId !== first);
+        expect(next.length).toBeGreaterThan(0);
+        const events = all(next);
+        // The new session has a landing page: the page the app last reported.
+        expect(kinds(events).slice(0, 3)).toEqual(["5:navigation", "4", "2"]);
+        expect(events.find((e) => e.type === 5).data.payload.routePattern).toBe("/shifts");
+        await page.close();
+    });
+    test("a navigation after the timeout opens the new session with its own snapshot only", async () => {
+        const { page, uploads } = await openPage();
+        const first = uploads[0].sessionId;
+        await settle(page, 31 * 60_000);
+        await page.evaluate(() => globalThis.__recorder.emitPageEvent({
+            href: "https://app.test/profile",
+            title: "Profile",
+            routePattern: "/profile",
+            params: null,
+        }));
+        await settle(page);
+        const events = all(uploads.filter((u) => u.sessionId !== first));
+        expect(kinds(events)).toEqual(["5:navigation", "4", "2"]);
+        expect(events[0].data.payload.routePattern).toBe("/profile");
+        await page.close();
+    });
+});

package/dist/src/session-lifecycle.d.ts

@@ -0,0 +1,45 @@
+/**
+ * When a recorded session ends.
+ *
+ * A session is one sitting. The recorder used to resolve its id once at start
+ * and never revisit it, so a tab left open stayed a single session for as long
+ * as the tab lived — production accumulated recordings of 20 days and 14k
+ * segments, which are neither watchable nor meaningful as analytics.
+ */
+/**
+ * User inactivity that ends a session. Matched to the session cookie's max-age
+ * so the in-tab and cross-navigation rules agree on when a session ends.
+ */
+export declare const SESSION_TIMEOUT_MS: number;
+/** rrweb event types, narrowed to what this module needs. */
+interface ActivityEvent {
+    type: number;
+    data?: {
+        source?: number;
+        tag?: string;
+    };
+}
+/** A Custom (5) event tagged "navigation": the app moved to another page. */
+export declare function isNavigation(event: ActivityEvent): boolean;
+/**
+ * Whether this event is evidence a person is still there.
+ *
+ * Keyframes (Meta + FullSnapshot) are not: the recorder takes them on a timer.
+ */
+export declare function isUserActivity(event: ActivityEvent): boolean;
+/**
+ * Whether the gap since `lastActivityAt` has ended the session.
+ *
+ * `lastActivityAt` of 0 means nothing has happened yet, which is the start of a
+ * session rather than the end of one.
+ */
+export declare function sessionExpired(lastActivityAt: number, now: number): boolean;
+/**
+ * Whether a session id cached in sessionStorage may still be used.
+ *
+ * sessionStorage is scoped to the tab, not to 30 minutes, so without this check
+ * a reload resurrects a session the cookie had already expired.
+ */
+export declare function storedSessionUsable(storedAt: number, now: number): boolean;
+export {};
+//# sourceMappingURL=session-lifecycle.d.ts.map

package/dist/src/session-lifecycle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-lifecycle.d.ts","sourceRoot":"","sources":["../../src/session-lifecycle.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH;;;GAGG;AACH,eAAO,MAAM,kBAAkB,QAAiB,CAAA;AAoBhD,6DAA6D;AAC7D,UAAU,aAAa;IACrB,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,GAAG,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;CACzC;AAED,6EAA6E;AAC7E,wBAAgB,YAAY,CAAC,KAAK,EAAE,aAAa,GAAG,OAAO,CAE1D;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,aAAa,GAAG,OAAO,CAM5D;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,cAAc,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAG3E;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAG1E"}

package/dist/src/session-lifecycle.js

@@ -0,0 +1,70 @@
+/**
+ * When a recorded session ends.
+ *
+ * A session is one sitting. The recorder used to resolve its id once at start
+ * and never revisit it, so a tab left open stayed a single session for as long
+ * as the tab lived — production accumulated recordings of 20 days and 14k
+ * segments, which are neither watchable nor meaningful as analytics.
+ */
+/**
+ * User inactivity that ends a session. Matched to the session cookie's max-age
+ * so the in-tab and cross-navigation rules agree on when a session ends.
+ */
+export const SESSION_TIMEOUT_MS = 30 * 60 * 1000;
+/**
+ * rrweb incremental sources that mean a human did something.
+ *
+ * Deliberately excludes mutations (source 0): a page that polls, animates or
+ * re-renders on a timer emits those forever with nobody watching, and counting
+ * them as activity is exactly what keeps an abandoned tab alive.
+ */
+const USER_ACTIVITY_SOURCES = new Set([
+    1, // MouseMove
+    2, // MouseInteraction
+    3, // Scroll
+    5, // Input
+    6, // TouchMove
+    7, // MediaInteraction
+    12, // Drag
+    14, // Selection
+]);
+/** A Custom (5) event tagged "navigation": the app moved to another page. */
+export function isNavigation(event) {
+    return event.type === 5 && event.data?.tag === "navigation";
+}
+/**
+ * Whether this event is evidence a person is still there.
+ *
+ * Keyframes (Meta + FullSnapshot) are not: the recorder takes them on a timer.
+ */
+export function isUserActivity(event) {
+    // A navigation is always a person doing something.
+    if (isNavigation(event))
+        return true;
+    // IncrementalSnapshot (3) — only the interaction sources count.
+    if (event.type === 3)
+        return USER_ACTIVITY_SOURCES.has(event.data?.source ?? -1);
+    return false;
+}
+/**
+ * Whether the gap since `lastActivityAt` has ended the session.
+ *
+ * `lastActivityAt` of 0 means nothing has happened yet, which is the start of a
+ * session rather than the end of one.
+ */
+export function sessionExpired(lastActivityAt, now) {
+    if (lastActivityAt <= 0)
+        return false;
+    return now - lastActivityAt > SESSION_TIMEOUT_MS;
+}
+/**
+ * Whether a session id cached in sessionStorage may still be used.
+ *
+ * sessionStorage is scoped to the tab, not to 30 minutes, so without this check
+ * a reload resurrects a session the cookie had already expired.
+ */
+export function storedSessionUsable(storedAt, now) {
+    if (!Number.isFinite(storedAt) || storedAt <= 0)
+        return false;
+    return now - storedAt < SESSION_TIMEOUT_MS;
+}

package/dist/src/session-lifecycle.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=session-lifecycle.test.d.ts.map

package/dist/src/session-lifecycle.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-lifecycle.test.d.ts","sourceRoot":"","sources":["../../src/session-lifecycle.test.ts"],"names":[],"mappings":""}