@lunardinos/browser 0.2.4 → 0.2.6

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;AAQhG,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,CA4hBzE"}
+{"version":3,"file":"recorder-core.d.ts","sourceRoot":"","sources":["../../src/recorder-core.ts"],"names":[],"mappings":"AACA,OAAO,EAA8C,KAAK,eAAe,EAAE,MAAM,eAAe,CAAA;AAWhG,YAAY,EAAE,eAAe,EAAE,MAAM,eAAe,CAAA;AAOpD,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,CA8jBzE"}

package/dist/src/recorder-core.js

@@ -1,24 +1,9 @@
-import record from "@lunardinos/rrweb-record";
+import record, {} from "@lunardinos/rrweb-record";
 import { createPersistence } from "./persistence";
-import { isUserActivity, SESSION_TIMEOUT_MS, sessionExpired, storedSessionUsable, } from "./session-lifecycle";
+import { isNavigation, isUserActivity, KEYFRAME_INTERVAL_MS, keyframeDue, 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 {
@@ -142,7 +127,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) {
@@ -177,15 +173,19 @@ 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;
+    // Periodic keyframe 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 keyframeIntervalId = null;
     let recording = false;
-    /** Last user activity, for {@link SESSION_TIMEOUT_MS}. */
+    /** Last user activity, for {@link SESSION_TIMEOUT_MS} and {@link keyframeDue}. */
     let lastActivityAt = 0;
+    /** User activity since the session cookie was last refreshed. */
+    let activitySinceTouch = false;
     /** 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
@@ -259,11 +259,14 @@ export function createLunarDinosRecorder(config) {
      * 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 full snapshot — without
-     * one it starts mid-stream against a DOM the player has never seen and can't
-     * be replayed at all.
+     * 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() {
+    function rotateSession(snapshot) {
         if (rotating)
             return;
         rotating = true;
@@ -276,11 +279,13 @@ export function createLunarDinosRecorder(config) {
             }
             lastActivityAt = Date.now();
             markActivity();
-            try {
-                record.takeFullSnapshot(true);
-            }
-            catch {
-                // Recording already stopped; the next start() will snapshot anyway.
+            if (snapshot) {
+                try {
+                    record.takeNavigationSnapshot(currentPage);
+                }
+                catch {
+                    // Recording already stopped; the next start() will snapshot anyway.
+                }
             }
         }
         finally {
@@ -290,6 +295,7 @@ export function createLunarDinosRecorder(config) {
     /** Persist the activity clock so a reload in the same tab can honour it. */
     function markActivity() {
         lastActivityAt = Date.now();
+        activitySinceTouch = true;
         if (typeof sessionStorage !== "undefined") {
             sessionStorage.setItem(SESSION_ACTIVITY_KEY, String(lastActivityAt));
         }
@@ -304,8 +310,12 @@ export function createLunarDinosRecorder(config) {
         if (vid)
             payload.visitorId = vid;
         const json = JSON.stringify(payload);
-        // Extend rolling session cookie on each flush
-        persistence.touchSession();
+        // Extend the rolling session cookie, but only for something a person did:
+        // keyframes and DOM churn flush too, and would keep an idle session alive.
+        if (activitySinceTouch) {
+            persistence.touchSession();
+            activitySinceTouch = false;
+        }
         // During page unload (beforeunload / MPA navigation), use sendBeacon
         // for guaranteed delivery. No async compression — page may tear down.
         if (options?.beacon) {
@@ -336,18 +346,25 @@ 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: redactAuthFromUrl(payload.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(),
-                locale: resolveLocale(payload.locale),
             });
         }
         catch {
@@ -466,18 +483,12 @@ 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: redactAuthFromUrl(startOpts.pageMetadata.href) ?? startOpts.pageMetadata.href,
-                    title: startOpts.pageMetadata.title,
-                    routePattern: startOpts.pageMetadata.routePattern ?? undefined,
-                    params: startOpts.pageMetadata.params,
-                    referrer: startOpts.pageMetadata.referrer ?? undefined,
-                    locale: resolveLocale(startOpts.pageMetadata.locale),
-                }
+                ? { ...currentPage, referrer: startOpts.pageMetadata.referrer ?? undefined }
                 : undefined,
             emit(event) {
                 const ev = event;
@@ -486,7 +497,7 @@ export function createLunarDinosRecorder(config) {
                 // old session before the event is recorded against it.
                 if (isUserActivity(ev) && !rotating) {
                     if (sessionExpired(lastActivityAt, Date.now()))
-                        rotateSession();
+                        rotateSession(!isNavigation(ev));
                     else
                         markActivity();
                 }
@@ -515,20 +526,25 @@ 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(() => {
+        // Take a periodic keyframe so long single-page sessions are split into
+        // bounded, independently-replayable segments — only while someone is there.
+        let lastTickAt = Date.now();
+        keyframeIntervalId = setInterval(() => {
+            const due = keyframeDue(lastActivityAt, lastTickAt, document.visibilityState !== "hidden");
+            lastTickAt = Date.now();
+            if (!due)
+                return;
             try {
                 record.takeFullSnapshot(true);
             }
             catch {
                 /* not recording / mid-teardown */
             }
-        }, FULL_SNAPSHOT_INTERVAL_MS);
+        }, KEYFRAME_INTERVAL_MS);
         return sessionId;
     }
     function stop() {
@@ -551,9 +567,9 @@ export function createLunarDinosRecorder(config) {
             clearInterval(intervalId);
             intervalId = null;
         }
-        if (checkoutIntervalId) {
-            clearInterval(checkoutIntervalId);
-            checkoutIntervalId = null;
+        if (keyframeIntervalId) {
+            clearInterval(keyframeIntervalId);
+            keyframeIntervalId = null;
         }
         stopFn?.();
         stopFn = null;

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,239 @@
+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. They are
+ * only taken while someone is there: the tab is visible and the user active.
+ */
+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();
+    // Count writes of the session cookie, which carries the rolling 30-minute expiry.
+    await page.addInitScript(() => {
+        const desc = Object.getOwnPropertyDescriptor(Document.prototype, "cookie");
+        const g = globalThis;
+        g.__sessionCookieWrites = 0;
+        Object.defineProperty(document, "cookie", {
+            get: () => desc.get.call(document),
+            set: (v) => {
+                if (v.startsWith("__ld_sid="))
+                    g.__sessionCookieWrites++;
+                desc.set.call(document, v);
+            },
+        });
+    });
+    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));
+}
+/** Make the tab hidden or visible, as switching tabs does. */
+async function setVisible(page, visible) {
+    await page.evaluate((v) => {
+        Object.defineProperty(document, "visibilityState", {
+            configurable: true,
+            get: () => (v ? "visible" : "hidden"),
+        });
+        Object.defineProperty(document, "hidden", { configurable: true, get: () => !v });
+        document.dispatchEvent(new Event("visibilitychange"));
+    }, visible);
+}
+/** Move the mouse a little, every 10 s for `minutes`: a user who is there. */
+async function stayActive(page, minutes) {
+    for (let i = 0; i < minutes * 6; i++) {
+        await page.mouse.move(100 + (i % 2) * 50, 100);
+        await settle(page, 10_000);
+    }
+}
+const cookieWrites = (page) => page.evaluate(() => globalThis.__sessionCookieWrites);
+const all = (uploads) => uploads.flatMap((u) => u.events);
+const fullSnapshots = (events) => events.filter((e) => e.type === 2);
+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 page.mouse.move(100, 100);
+        await settle(page, 60_000);
+        expect(kinds(all(uploads).slice(before))).toEqual(["4", "2"]);
+        await page.close();
+    });
+    test("an active user in a visible tab gets a keyframe every interval", async () => {
+        const { page, uploads } = await openPage();
+        const before = all(uploads).length;
+        await stayActive(page, 5);
+        expect(kinds(all(uploads).slice(before))).toEqual([
+            "4",
+            "2",
+            "4",
+            "2",
+            "4",
+            "2",
+            "4",
+            "2",
+            "4",
+            "2",
+        ]);
+        await page.close();
+    });
+    test("no keyframes once the user is idle", async () => {
+        const { page, uploads } = await openPage();
+        // Nobody touches the page after it opens.
+        const before = all(uploads).length;
+        await settle(page, 10 * 60_000);
+        expect(fullSnapshots(all(uploads).slice(before))).toEqual([]);
+        await page.close();
+    });
+    test("no keyframes while the tab is hidden", async () => {
+        const { page, uploads } = await openPage();
+        await setVisible(page, false);
+        const before = all(uploads).length;
+        await stayActive(page, 3);
+        expect(fullSnapshots(all(uploads).slice(before))).toEqual([]);
+        await page.close();
+    });
+    test("after the user comes back, the next keyframe comes within the interval", async () => {
+        const { page, uploads } = await openPage();
+        await setVisible(page, false);
+        await settle(page, 10 * 60_000);
+        await setVisible(page, true);
+        const before = all(uploads).length;
+        await page.mouse.move(100, 100);
+        await settle(page, 60_000);
+        expect(kinds(all(uploads).slice(before))).toEqual(["4", "2"]);
+        await page.close();
+    });
+    test("keyframes and DOM churn don't extend the session cookie; user activity does", async () => {
+        const { page } = await openPage();
+        const opened = await cookieWrites(page);
+        // The first tick's keyframe, and a page re-rendering on its own.
+        await page.evaluate(() => {
+            document.getElementById("app").append("tick");
+        });
+        await settle(page, 60_000);
+        expect(await cookieWrites(page)).toBe(opened);
+        await page.mouse.move(100, 100);
+        await settle(page);
+        expect(await cookieWrites(page)).toBe(opened + 1);
+        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: at most the first keyframe is 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

@@ -16,9 +16,16 @@ interface ActivityEvent {
     type: number;
     data?: {
         source?: number;
+        tag?: string;
     };
 }
-/** Whether this event is evidence a person is still there. */
+/** 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.
@@ -34,5 +41,26 @@ export declare function sessionExpired(lastActivityAt: number, now: number): boo
  * a reload resurrects a session the cookie had already expired.
  */
 export declare function storedSessionUsable(storedAt: number, now: number): boolean;
+/**
+ * How often to take a keyframe (Meta + FullSnapshot) while the user is active.
+ *
+ * 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. Each snapshot is the whole
+ * DOM, but stylesheets and images are deduplicated, so the marginal cost is
+ * mostly the node tree, which compresses well.
+ */
+export declare const KEYFRAME_INTERVAL_MS: number;
+/**
+ * Whether the periodic keyframe should be taken now.
+ *
+ * Only while a person is there: the tab is visible and they did something
+ * since the previous tick. Idle users and background tabs are the bulk of
+ * recorded time, and a keyframe of a page nobody is touching is bytes for
+ * nothing. Comparing against the previous tick rather than a fixed window
+ * keeps this right when timers fire late, so keyframes always resume at the
+ * first tick after the user returns, within an interval.
+ */
+export declare function keyframeDue(lastActivityAt: number, lastTickAt: number, visible: boolean): boolean;
 export {};
 //# sourceMappingURL=session-lifecycle.d.ts.map

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

@@ -1 +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,CAAA;KAAE,CAAA;CAC3B;AAED,8DAA8D;AAC9D,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"}
+{"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;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,oBAAoB,QAAY,CAAA;AAE7C;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CAAC,cAAc,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAEjG"}

package/dist/src/session-lifecycle.js

@@ -28,10 +28,18 @@ const USER_ACTIVITY_SOURCES = new Set([
     12, // Drag
     14, // Selection
 ]);
-/** Whether this event is evidence a person is still there. */
+/** 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) {
-    // Pageview (7) — a navigation is always a person doing something.
-    if (event.type === 7)
+    // A navigation is always a person doing something.
+    if (isNavigation(event))
         return true;
     // IncrementalSnapshot (3) — only the interaction sources count.
     if (event.type === 3)
@@ -60,3 +68,26 @@ export function storedSessionUsable(storedAt, now) {
         return false;
     return now - storedAt < SESSION_TIMEOUT_MS;
 }
+/**
+ * How often to take a keyframe (Meta + FullSnapshot) while the user is active.
+ *
+ * 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. Each snapshot is the whole
+ * DOM, but stylesheets and images are deduplicated, so the marginal cost is
+ * mostly the node tree, which compresses well.
+ */
+export const KEYFRAME_INTERVAL_MS = 60 * 1000;
+/**
+ * Whether the periodic keyframe should be taken now.
+ *
+ * Only while a person is there: the tab is visible and they did something
+ * since the previous tick. Idle users and background tabs are the bulk of
+ * recorded time, and a keyframe of a page nobody is touching is bytes for
+ * nothing. Comparing against the previous tick rather than a fixed window
+ * keeps this right when timers fire late, so keyframes always resume at the
+ * first tick after the user returns, within an interval.
+ */
+export function keyframeDue(lastActivityAt, lastTickAt, visible) {
+    return visible && lastActivityAt > lastTickAt;
+}

package/dist/src/session-lifecycle.test.js

@@ -1,5 +1,5 @@
 import { describe, expect, test } from "bun:test";
-import { isUserActivity, SESSION_TIMEOUT_MS, sessionExpired, storedSessionUsable, } from "./session-lifecycle";
+import { isUserActivity, KEYFRAME_INTERVAL_MS, keyframeDue, SESSION_TIMEOUT_MS, sessionExpired, storedSessionUsable, } from "./session-lifecycle";
 /**
  * These rules decide how a visitor's time is cut into sessions, and both failure
  * directions are expensive: too permissive and a tab left open becomes a 20-day
@@ -19,7 +19,15 @@ describe("isUserActivity", () => {
         expect(isUserActivity(inc(14))).toBe(true); // selection
     });
     test("a navigation is always activity", () => {
-        expect(isUserActivity({ type: 7 })).toBe(true);
+        expect(isUserActivity({ type: 5, data: { tag: "navigation" } })).toBe(true);
+    });
+    test("a keyframe is not activity", () => {
+        // The periodic Meta + FullSnapshot is the recorder's doing, not a person's.
+        expect(isUserActivity({ type: 4 })).toBe(false);
+        expect(isUserActivity({ type: 2 })).toBe(false);
+    });
+    test("other custom events are not activity", () => {
+        expect(isUserActivity({ type: 5, data: { tag: "session:meta" } })).toBe(false);
     });
     test("does NOT count DOM mutations", () => {
         // The whole point: a polling or animating page emits these forever with
@@ -83,3 +91,23 @@ describe("storedSessionUsable", () => {
         expect(storedSessionUsable(0, NOW)).toBe(false);
     });
 });
+describe("keyframeDue", () => {
+    const TICK = NOW + KEYFRAME_INTERVAL_MS;
+    test("takes a keyframe while the user is active and the tab is visible", () => {
+        expect(keyframeDue(TICK - 1_000, NOW, true)).toBe(true);
+    });
+    test("not while the tab is hidden, however recent the activity", () => {
+        expect(keyframeDue(TICK - 1_000, NOW, false)).toBe(false);
+    });
+    test("not when nothing happened since the previous tick", () => {
+        // The snapshot would only repeat what the player can already rebuild, and
+        // idle tabs are most tabs.
+        expect(keyframeDue(NOW, NOW, true)).toBe(false);
+        expect(keyframeDue(NOW - 20 * 24 * 60 * 60_000, NOW, true)).toBe(false);
+    });
+    test("activity right after a tick still counts when the next one fires late", () => {
+        // Timers drift: a busy or throttled page fires the next tick well past the
+        // interval, and the activity must not have aged out of a fixed window.
+        expect(keyframeDue(NOW + 1, NOW, true)).toBe(true);
+    });
+});

package/dist/src/testing/measure-bytes.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=measure-bytes.d.ts.map

package/dist/src/testing/measure-bytes.d.ts.map

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