@dash0/sdk-web 0.24.0 → 0.26.0

package/dist/modules/api/init.js

@@ -11,6 +11,7 @@ import { startNavigationInstrumentation } from "../instrumentations/navigation";
 import { initializeTabId } from "../utils/tab-id";
 import { pickFirstString } from "./browser-env";
 import { applyVcsResourceAttributes } from "./vcs";
+import { armSessionRecording } from "../instrumentations/session-recording";
 let hasBeenInitialised = false;
 export function init(opts) {
     if (hasBeenInitialised) {
@@ -50,6 +51,7 @@ export function init(opts) {
         "headersToCapture",
         "urlAttributeScrubber",
         "pageViewInstrumentation",
+        "sessionRecording",
         "enableTransportCompression",
     ])));
     initializePropagators(opts);
@@ -81,6 +83,9 @@ export function init(opts) {
     if (isInstrumentationEnabled("@dash0/xhr", opts)) {
         instrumentXhr();
     }
+    if (isInstrumentationEnabled("@dash0/session-recording", opts)) {
+        armSessionRecording();
+    }
     hasBeenInitialised = true;
 }
 function initializeResourceAttributes(opts) {
@@ -206,7 +211,10 @@ function merge(target, source) {
                 typeof dstVal === "object" &&
                 dstVal !== null &&
                 !Array.isArray(dstVal)) {
-                result[key] = { ...dstVal, ...srcVal };
+                // Like the top-level rule above, an explicit `undefined` inside a nested object means "not provided" and
+                // must not erase the default. Otherwise `sessionRecording: { maskAllInputs: someUnsetFlag }` would
+                // silently turn input masking off.
+                result[key] = { ...dstVal, ...withoutUndefined(srcVal) };
             }
             else {
                 result[key] = srcVal;
@@ -215,3 +223,12 @@ function merge(target, source) {
     }
     return result;
 }
+function withoutUndefined(obj) {
+    const result = {};
+    for (const key of Object.keys(obj)) {
+        if (obj[key] !== undefined) {
+            result[key] = obj[key];
+        }
+    }
+    return result;
+}

package/dist/modules/api/init_test.js

@@ -16,6 +16,9 @@ vi.mock("../instrumentations/http/xhr", () => ({
 vi.mock("../instrumentations/navigation", () => ({
     startNavigationInstrumentation: vi.fn(),
 }));
+vi.mock("../instrumentations/session-recording", () => ({
+    armSessionRecording: vi.fn(),
+}));
 // Mock the utils module to control loc.hostname
 vi.mock("../utils", async () => {
     const actual = await vi.importActual("../utils");
@@ -29,6 +32,7 @@ import { instrumentFetch } from "../instrumentations/http/fetch";
 import { instrumentXhr } from "../instrumentations/http/xhr";
 import { startNavigationInstrumentation } from "../instrumentations/navigation";
 import { startWebVitalsInstrumentation } from "../instrumentations/web-vitals";
+import { armSessionRecording } from "../instrumentations/session-recording";
 describe("init", () => {
     const baseOptions = {
         serviceName: "test-service",
@@ -51,6 +55,27 @@ describe("init", () => {
     afterEach(() => {
         vi.clearAllMocks();
     });
+    describe("nested option merging", () => {
+        it("keeps nested defaults when an override is explicitly undefined", () => {
+            init({
+                ...baseOptions,
+                sessionRecording: { maskAllInputs: undefined, chunkMaxMillis: 1000 },
+            });
+            expect(vars.sessionRecording.maskAllInputs).toBe(true);
+            expect(vars.sessionRecording.blockClass).toBe("dash0-block");
+            expect(vars.sessionRecording.chunkMaxMillis).toBe(1000);
+        });
+        it("still lets an explicit false override a nested default", () => {
+            init({
+                ...baseOptions,
+                sessionRecording: { maskAllInputs: false },
+                pageViewInstrumentation: { trackVirtualPageViews: false },
+            });
+            expect(vars.sessionRecording.maskAllInputs).toBe(false);
+            expect(vars.pageViewInstrumentation.trackVirtualPageViews).toBe(false);
+            expect(vars.pageViewInstrumentation.includeParts).toEqual([]);
+        });
+    });
     describe("instrumentation enablement", () => {
         it("should enable all instrumentations when enabledInstrumentations is undefined", async () => {
             init({
@@ -69,6 +94,7 @@ describe("init", () => {
             "@dash0/error",
             "@dash0/fetch",
             "@dash0/xhr",
+            "@dash0/session-recording",
         ];
         const instrumentationMocks = {
             "@dash0/navigation": startNavigationInstrumentation,
@@ -76,6 +102,7 @@ describe("init", () => {
             "@dash0/error": startErrorInstrumentation,
             "@dash0/fetch": instrumentFetch,
             "@dash0/xhr": instrumentXhr,
+            "@dash0/session-recording": armSessionRecording,
         };
         instrumentations.forEach((instrumentation) => {
             it(`should enable ${instrumentation} instrumentation when present in enabledInstrumentations array`, async () => {

package/dist/modules/api/session-recording.js

@@ -0,0 +1,38 @@
+import { debug, win } from "../utils";
+import { GLOBAL_RECORDER_KEY, registerSessionRecorder, stopSessionRecording as stopRecording, } from "../instrumentations/session-recording";
+/**
+ * Starts session recording with the given recorder. Pass `recorder` from `@dash0/sdk-web/session-recording`.
+ * When `recorder` is omitted, the SDK looks for `window.dash0Recorder`, which the
+ * `dash0-session-recording.iife.js` script sets. Calling this is not required when that script is used: `init()`
+ * picks up `window.dash0Recorder` on its own, regardless of the order in which the scripts execute.
+ *
+ * Recording only starts once `init()` has run with a sampled session. It is safe to call this before `init()`;
+ * the recorder is kept and recording starts as soon as the SDK is initialized. The recording is transmitted
+ * as `browser.session_recording` log records that share one trace ID, which embeds the session ID.
+ *
+ * Only the visible document is recorded. A tab that is hidden — switched away from, or opened in the
+ * background — stops recording and flushes what it buffered, and starts a fresh recording when it is shown
+ * again. So a session is a sequence of recordings that do not overlap in time, which is what lets the whole
+ * session, tab switches included, be replayed as one.
+ */
+export function startSessionRecording(recorder) {
+    // The script entrypoint forwards dash0("startSessionRecording", ...) arguments without type checking,
+    // so malformed calls must degrade to a logged no-op instead of throwing. An uncaught throw here would
+    // abort the command-queue drain and drop all subsequently queued api calls.
+    const r = recorder ?? win?.[GLOBAL_RECORDER_KEY];
+    if (typeof r !== "function") {
+        debug("startSessionRecording requires a recorder. Import `recorder` from `@dash0/sdk-web/session-recording` or load dash0-session-recording.iife.js. Ignoring call.");
+        return;
+    }
+    registerSessionRecorder(r);
+}
+/**
+ * Stops the running session recording and transmits any buffered events. Calling this when no recording is
+ * running is a no-op.
+ *
+ * Unlike the automatic pause while a tab is hidden, this is final: recording does not resume when the tab
+ * becomes visible again. Call `startSessionRecording()` to record again.
+ */
+export function stopSessionRecording() {
+    stopRecording();
+}

package/dist/modules/api/session-recording_test.js

@@ -0,0 +1,36 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+vi.mock("../instrumentations/session-recording", () => ({
+    GLOBAL_RECORDER_KEY: "dash0Recorder",
+    registerSessionRecorder: vi.fn(),
+    stopSessionRecording: vi.fn(),
+}));
+import { registerSessionRecorder, stopSessionRecording as stopImpl } from "../instrumentations/session-recording";
+import { startSessionRecording, stopSessionRecording } from "./session-recording";
+import { win } from "../utils";
+const globalObject = win;
+describe("startSessionRecording api", () => {
+    beforeEach(() => {
+        vi.clearAllMocks();
+        delete globalObject.dash0Recorder;
+    });
+    it("registers an explicitly passed recorder", () => {
+        const recorder = vi.fn();
+        startSessionRecording(recorder);
+        expect(registerSessionRecorder).toHaveBeenCalledWith(recorder);
+    });
+    it("falls back to window.dash0Recorder", () => {
+        const recorder = vi.fn();
+        globalObject.dash0Recorder = recorder;
+        startSessionRecording();
+        expect(registerSessionRecorder).toHaveBeenCalledWith(recorder);
+    });
+    it("ignores calls without a usable recorder instead of throwing", () => {
+        expect(() => startSessionRecording()).not.toThrow();
+        expect(() => startSessionRecording("nope")).not.toThrow();
+        expect(registerSessionRecorder).not.toHaveBeenCalled();
+    });
+    it("delegates stop", () => {
+        stopSessionRecording();
+        expect(stopImpl).toHaveBeenCalledTimes(1);
+    });
+});

package/dist/modules/entrypoint/npm-package.js

@@ -8,6 +8,7 @@ export * from "../api/log-level";
 export { terminateSession } from "../api/session";
 export { reportError } from "../api/report-error";
 export { startView } from "../api/start-view";
+export { startSessionRecording, stopSessionRecording } from "../api/session-recording";
 export function init(opts) {
     debug(`${INIT_MESSAGE} (via package)`);
     initApi(opts);

package/dist/modules/entrypoint/script.js

@@ -8,6 +8,7 @@ import { addSignalAttribute, removeSignalAttribute } from "../api/attributes";
 import { sendEvent } from "../api/events";
 import { setActiveLogLevel } from "../api/log-level";
 import { startView } from "../api/start-view";
+import { startSessionRecording, stopSessionRecording } from "../api/session-recording";
 /**
  * All the APIs exposed through the script tag via `dash0('{{api name}}')`
  */
@@ -22,6 +23,8 @@ const scriptApis = {
     setActiveLogLevel,
     sendEvent,
     startView,
+    startSessionRecording,
+    stopSessionRecording,
 };
 init();
 function init() {

package/dist/modules/entrypoint/session-recording-script.js

@@ -0,0 +1,19 @@
+/**
+ * Script-tag entrypoint, built to `dist/dash0-session-recording.iife.js`.
+ *
+ * This bundle contains only rrweb's recorder. It must not import any SDK module (see eslint.config.js), so the
+ * main SDK bundle stays the single owner of configuration, session and transport state. It hands the recorder
+ * to the SDK in two ways, so it can be loaded in any order relative to the initializer snippet and `dash0.iife.js`:
+ *
+ * - `window.dash0Recorder`: picked up by the SDK when `init()` runs. Covers the case where this bundle executes
+ *   before the initializer snippet has defined the `dash0` command queue.
+ * - `dash0("startSessionRecording", record)`: covers the case where the SDK is already initialized, or the
+ *   command queue exists and will be drained on `init()`.
+ */
+/* eslint-disable no-restricted-globals */
+import { record } from "@rrweb/record";
+window.dash0Recorder = record;
+const dash0 = window.dash0;
+if (typeof dash0 === "function") {
+    dash0("startSessionRecording", record);
+}

package/dist/modules/entrypoint/session-recording.js

@@ -0,0 +1,11 @@
+/**
+ * npm entrypoint of `@dash0/sdk-web/session-recording`.
+ *
+ * This bundle contains only rrweb's recorder. It must not import any SDK module (see eslint.config.js), so the
+ * main SDK bundle stays the single owner of configuration, session and transport state.
+ */
+import { record } from "@rrweb/record";
+/**
+ * The rrweb recorder. Pass it to `init({ sessionRecording: { recorder } })` or to `startSessionRecording(recorder)`.
+ */
+export const recorder = record;

package/dist/modules/instrumentations/session-recording/chunker.js

@@ -0,0 +1,70 @@
+import { setTimeout, clearTimeout } from "../../utils/timers";
+const RRWEB_EVENT_TYPE_FULL_SNAPSHOT = 2;
+const RRWEB_EVENT_TYPE_META = 4;
+/**
+ * Buffers rrweb events and hands them out as chunks. A chunk closes when its serialized size reaches
+ * `maxBytes`, when `maxMillis` have passed since its first event, when a new full snapshot begins, or when
+ * `flush()` is called. Events are serialized once, on arrival, so a flush is a join and not a second stringify.
+ */
+export function newChunker(opts) {
+    let serialized = [];
+    let byteSize = 0;
+    let hasSnapshot = false;
+    let startTime = 0;
+    let endTime = 0;
+    let seq = 0;
+    let pendingFlushTimeout = null;
+    return { add, flush, discard };
+    function add(event) {
+        // A Meta event announces a new full snapshot. Close the current chunk first so the snapshot starts a fresh
+        // one and a replay can begin at that chunk.
+        if (event.type === RRWEB_EVENT_TYPE_META && serialized.length > 0) {
+            flush();
+        }
+        const json = JSON.stringify(event);
+        if (json == null)
+            return;
+        if (serialized.length === 0) {
+            startTime = event.timestamp;
+            pendingFlushTimeout = setTimeout(flush, opts.maxMillis);
+        }
+        serialized.push(json);
+        byteSize += json.length;
+        endTime = event.timestamp;
+        if (event.type === RRWEB_EVENT_TYPE_FULL_SNAPSHOT) {
+            hasSnapshot = true;
+        }
+        if (byteSize >= opts.maxBytes) {
+            flush();
+        }
+    }
+    function discard() {
+        clearPendingFlush();
+        serialized = [];
+        byteSize = 0;
+        hasSnapshot = false;
+    }
+    function clearPendingFlush() {
+        if (pendingFlushTimeout != null) {
+            clearTimeout(pendingFlushTimeout);
+            pendingFlushTimeout = null;
+        }
+    }
+    function flush() {
+        clearPendingFlush();
+        if (serialized.length === 0)
+            return;
+        const chunk = {
+            seq: seq++,
+            body: "[" + serialized.join(",") + "]",
+            eventCount: serialized.length,
+            hasSnapshot,
+            startTime,
+            endTime,
+        };
+        serialized = [];
+        byteSize = 0;
+        hasSnapshot = false;
+        opts.onChunk(chunk);
+    }
+}

package/dist/modules/instrumentations/session-recording/chunker_test.js

@@ -0,0 +1,125 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { newChunker } from "./chunker";
+// The SDK's timer wrapper captures window.setTimeout at import time, before vitest installs fake timers.
+// Resolve the globals lazily so vi.useFakeTimers() takes effect.
+vi.mock("../../utils/timers", () => ({
+    setTimeout: (...args) => globalThis.setTimeout(...args),
+    clearTimeout: (...args) => globalThis.clearTimeout(...args),
+}));
+const META = 4;
+const FULL_SNAPSHOT = 2;
+const INCREMENTAL = 3;
+function event(type, timestamp, data = {}) {
+    return { type, timestamp, data };
+}
+describe("session recording chunker", () => {
+    let chunks;
+    beforeEach(() => {
+        vi.useFakeTimers();
+        chunks = [];
+    });
+    afterEach(() => {
+        vi.useRealTimers();
+    });
+    function create(maxBytes = 10_000, maxMillis = 5000) {
+        return newChunker({ maxBytes, maxMillis, onChunk: (c) => chunks.push(c) });
+    }
+    it("does nothing on flush when empty", () => {
+        const chunker = create();
+        chunker.flush();
+        expect(chunks).toEqual([]);
+    });
+    it("discards buffered events and the pending time-based flush", () => {
+        const chunker = create();
+        chunker.add(event(META, 1000));
+        chunker.add(event(FULL_SNAPSHOT, 1001));
+        chunker.discard();
+        vi.advanceTimersByTime(10_000);
+        expect(chunks).toEqual([]);
+        // The chunker stays usable, and the dropped events do not leak into the next chunk.
+        chunker.add(event(INCREMENTAL, 2000));
+        chunker.flush();
+        expect(chunks).toHaveLength(1);
+        expect(chunks[0].seq).toBe(0);
+        expect(chunks[0].eventCount).toBe(1);
+        expect(chunks[0].hasSnapshot).toBe(false);
+    });
+    it("flushes on explicit flush with a serialized JSON array body", () => {
+        const chunker = create();
+        chunker.add(event(META, 1000, { href: "http://x" }));
+        chunker.add(event(FULL_SNAPSHOT, 1001));
+        chunker.add(event(INCREMENTAL, 1002));
+        chunker.flush();
+        expect(chunks).toHaveLength(1);
+        const chunk = chunks[0];
+        expect(chunk.seq).toBe(0);
+        expect(chunk.eventCount).toBe(3);
+        expect(chunk.hasSnapshot).toBe(true);
+        expect(chunk.startTime).toBe(1000);
+        expect(chunk.endTime).toBe(1002);
+        expect(JSON.parse(chunk.body)).toEqual([
+            { type: META, timestamp: 1000, data: { href: "http://x" } },
+            { type: FULL_SNAPSHOT, timestamp: 1001, data: {} },
+            { type: INCREMENTAL, timestamp: 1002, data: {} },
+        ]);
+    });
+    it("flushes when maxMillis elapse after the first event", () => {
+        const chunker = create(10_000, 5000);
+        chunker.add(event(INCREMENTAL, 1));
+        vi.advanceTimersByTime(4999);
+        expect(chunks).toHaveLength(0);
+        chunker.add(event(INCREMENTAL, 2));
+        vi.advanceTimersByTime(1);
+        expect(chunks).toHaveLength(1);
+        expect(chunks[0].eventCount).toBe(2);
+    });
+    it("flushes when the serialized size reaches maxBytes", () => {
+        const chunker = create(100, 60_000);
+        const payload = "x".repeat(40);
+        chunker.add(event(INCREMENTAL, 1, payload)); // ~70 bytes
+        expect(chunks).toHaveLength(0);
+        chunker.add(event(INCREMENTAL, 2, payload)); // crosses 100
+        expect(chunks).toHaveLength(1);
+        expect(chunks[0].eventCount).toBe(2);
+    });
+    it("emits an oversized single event as its own chunk", () => {
+        const chunker = create(50, 60_000);
+        chunker.add(event(FULL_SNAPSHOT, 1, "y".repeat(500)));
+        expect(chunks).toHaveLength(1);
+        expect(chunks[0].eventCount).toBe(1);
+        expect(chunks[0].hasSnapshot).toBe(true);
+    });
+    it("closes the current chunk when a Meta event starts a new snapshot", () => {
+        const chunker = create();
+        chunker.add(event(META, 1));
+        chunker.add(event(FULL_SNAPSHOT, 2));
+        chunker.add(event(INCREMENTAL, 3));
+        expect(chunks).toHaveLength(0);
+        chunker.add(event(META, 4));
+        expect(chunks).toHaveLength(1);
+        expect(chunks[0].eventCount).toBe(3);
+        chunker.add(event(FULL_SNAPSHOT, 5));
+        chunker.flush();
+        expect(chunks).toHaveLength(2);
+        expect(chunks[1].eventCount).toBe(2);
+        expect(chunks[1].hasSnapshot).toBe(true);
+    });
+    it("increments seq across chunks and resets hasSnapshot", () => {
+        const chunker = create();
+        chunker.add(event(FULL_SNAPSHOT, 1));
+        chunker.flush();
+        chunker.add(event(INCREMENTAL, 2));
+        chunker.flush();
+        chunker.add(event(INCREMENTAL, 3));
+        chunker.flush();
+        expect(chunks.map((c) => c.seq)).toEqual([0, 1, 2]);
+        expect(chunks.map((c) => c.hasSnapshot)).toEqual([true, false, false]);
+    });
+    it("cancels the pending timer on flush so it does not fire twice", () => {
+        const chunker = create(10_000, 1000);
+        chunker.add(event(INCREMENTAL, 1));
+        chunker.flush();
+        vi.advanceTimersByTime(5000);
+        expect(chunks).toHaveLength(1);
+    });
+});

package/dist/modules/instrumentations/session-recording/index.js

@@ -0,0 +1,235 @@
+import { vars } from "../../vars";
+import { sessionId } from "../../api/session";
+import { debug, doc, generateUniqueId, isSessionSampledIn, TRACE_ID_BYTES, warn, win } from "../../utils";
+import { generateTraceId } from "../../utils/trace-id";
+import { generateSpanId } from "../../utils/span-id";
+import { isUrlIgnored } from "../../utils/ignore-rules";
+import { addEventListener } from "../../utils/listeners";
+import { onLastChance } from "../../utils/on-last-chance";
+import { sendSessionRecordingChunk } from "../../transport";
+import { newChunker } from "./chunker";
+import { buildSessionRecordingLog } from "./log";
+/**
+ * Global set by `dash0-session-recording.iife.js`. Read by `armSessionRecording()` and by
+ * `startSessionRecording()` when called without a recorder.
+ */
+export const GLOBAL_RECORDER_KEY = "dash0Recorder";
+let recorder;
+let armed = false;
+let stopRecorder;
+let chunker;
+let lastChanceRegistered = false;
+let visibilityRegistered = false;
+// Set by the public `stopSessionRecording()`, so a visibility change does not resurrect a recording the
+// consumer deliberately ended. Cleared by an explicit start: registering a recorder or arming.
+let stoppedByConsumer = false;
+// True while flushing a document that may not live much longer. The chunk emitted then must be sent
+// uncompressed: gzip is asynchronous, and a document that is being unloaded — or that has just been hidden,
+// and may be unloaded or throttled at any moment — may never get to the `fetch()` behind the await.
+let flushingWhileDocumentMayEnd = false;
+/**
+ * Makes a recorder available. Called from the public `startSessionRecording` API, which the
+ * `dash0-session-recording.iife.js` script and npm consumers use. Recording starts as soon as both a recorder
+ * is registered and `init()` has armed session recording, in either order.
+ */
+export function registerSessionRecorder(r) {
+    recorder = r;
+    stoppedByConsumer = false;
+    if (armed) {
+        start();
+    }
+}
+/**
+ * Called from `init()` once configuration is in place and the session is sampled.
+ *
+ * Recorder precedence: `sessionRecording.recorder` from the init options, then a recorder registered through
+ * `startSessionRecording(recorder)`, then `window.dash0Recorder`. The last one is set by
+ * `dash0-session-recording.iife.js`, and is the only handover that works when that script executes before the
+ * initializer snippet has defined the `dash0` command queue.
+ */
+export function armSessionRecording() {
+    armed = true;
+    stoppedByConsumer = false;
+    if (vars.sessionRecording.recorder) {
+        recorder = vars.sessionRecording.recorder;
+    }
+    else if (!recorder) {
+        const globalRecorder = win?.[GLOBAL_RECORDER_KEY];
+        if (typeof globalRecorder === "function") {
+            recorder = globalRecorder;
+        }
+    }
+    if (recorder) {
+        start();
+    }
+}
+export function stopSessionRecording() {
+    stoppedByConsumer = true;
+    teardown();
+}
+export function isSessionRecording() {
+    return stopRecorder != null;
+}
+/**
+ * Stops the recorder and flushes what it buffered. Shared by the public stop and by the visibility handler,
+ * which differ only in whether the consumer asked for it.
+ */
+function teardown() {
+    if (stopRecorder) {
+        try {
+            stopRecorder();
+        }
+        catch (e) {
+            debug("Failed to stop session recorder", e);
+        }
+        stopRecorder = undefined;
+    }
+    chunker?.flush();
+    chunker = undefined;
+}
+/**
+ * Whether the document is not on screen. Treats an absent `visibilityState` as visible, so an environment
+ * without the API records exactly as it did before rather than never recording at all.
+ *
+ * `prerender` counts as hidden: nobody is looking at a prerendered page.
+ */
+function isDocumentHidden() {
+    const state = doc?.visibilityState;
+    return state != null && state !== "visible";
+}
+/**
+ * Recording follows visibility: a hidden tab is torn down and a shown tab starts a new recorder run.
+ *
+ * This is what lets one replayer play a whole session. rrweb's Replayer rebuilds from any full snapshot it
+ * plays through, but each rebuild resets its node-id mirror, so events from a document other than the one
+ * that produced the newest snapshot would address the wrong nodes. Recording only the visible document keeps
+ * the runs of a session from overlapping, so they concatenate into a single coherent stream. `record()` takes
+ * a full snapshot when it starts, so every run opens with one and needs no separate snapshot call.
+ *
+ * Not recording hidden tabs is also why a session stays small: a background tab left open for hours used to
+ * record mutations nobody ever saw.
+ */
+function registerVisibilityHandling() {
+    if (visibilityRegistered || !doc) {
+        return;
+    }
+    visibilityRegistered = true;
+    addEventListener(doc, "visibilitychange", () => {
+        if (isDocumentHidden()) {
+            // Flushed the same way as an unload: a hidden document can be discarded or throttled before an
+            // asynchronous gzip completes.
+            flushingWhileDocumentMayEnd = true;
+            try {
+                teardown();
+            }
+            finally {
+                flushingWhileDocumentMayEnd = false;
+            }
+            return;
+        }
+        if (!stoppedByConsumer) {
+            start();
+        }
+    });
+}
+function start() {
+    if (stopRecorder) {
+        debug("Session recording already running. Ignoring start.");
+        return;
+    }
+    if (!recorder || !win)
+        return;
+    const settings = vars.sessionRecording;
+    if (!vars.isSessionSampled) {
+        debug("Session is not sampled. Session recording will not start.");
+        return;
+    }
+    if (!isSessionSampledIn(sessionId ?? "", settings.samplingRate ?? 100)) {
+        debug("Session is not sampled for recording. Session recording will not start.");
+        return;
+    }
+    if (isUrlIgnored(win.location.href)) {
+        debug("Page URL is ignored. Session recording will not start.");
+        return;
+    }
+    registerVisibilityHandling();
+    if (isDocumentHidden()) {
+        // A tab opened in the background — ctrl+click, `target=_blank`, a restored session — must not record
+        // until it is first shown. The listener above starts it then.
+        debug("Document is hidden. Session recording will start once it becomes visible.");
+        return;
+    }
+    const traceId = generateTraceId(sessionId);
+    const stream = {
+        recordingId: generateUniqueId(TRACE_ID_BYTES),
+        traceId,
+        spanId: generateSpanId(traceId),
+    };
+    const c = newChunker({
+        maxBytes: settings.chunkMaxBytes ?? 48000,
+        maxMillis: settings.chunkMaxMillis ?? 5000,
+        onChunk: (chunk) => {
+            try {
+                sendSessionRecordingChunk(buildSessionRecordingLog(stream, chunk), {
+                    compress: !flushingWhileDocumentMayEnd,
+                });
+            }
+            catch (e) {
+                warn("Failed to transmit session recording chunk", e);
+            }
+        },
+    });
+    chunker = c;
+    try {
+        stopRecorder = recorder({
+            // rrweb can still emit after its stop function ran (trailing throttle timers), and a recorder that failed
+            // to start may have emitted already. Only accept events while this chunker is the active one.
+            emit: (event) => {
+                if (chunker === c)
+                    c.add(event);
+            },
+            checkoutEveryNms: settings.checkoutEveryNms,
+            maskAllInputs: settings.maskAllInputs,
+            maskTextClass: settings.maskTextClass,
+            maskTextSelector: settings.maskTextSelector,
+            maskInputFn: settings.maskInputFn,
+            maskTextFn: settings.maskTextFn,
+            blockClass: settings.blockClass,
+            blockSelector: settings.blockSelector,
+            recordCanvas: settings.recordCanvas,
+            collectFonts: settings.collectFonts,
+        });
+    }
+    catch (e) {
+        warn("Failed to start session recorder", e);
+        abandonChunker(c);
+        return;
+    }
+    if (!stopRecorder) {
+        // rrweb returns undefined when it refuses to record, e.g. in an unsupported environment.
+        warn("Session recorder did not start.");
+        abandonChunker(c);
+        return;
+    }
+    if (!lastChanceRegistered) {
+        lastChanceRegistered = true;
+        onLastChance(() => {
+            flushingWhileDocumentMayEnd = true;
+            try {
+                chunker?.flush();
+            }
+            finally {
+                flushingWhileDocumentMayEnd = false;
+            }
+        });
+    }
+    debug("Session recording started", stream);
+}
+/**
+ * The recorder did not start, but it may already have emitted events into `c` and armed its flush timer. Drop
+ * them so no chunk of a stream that never started is transmitted later.
+ */
+function abandonChunker(c) {
+    c.discard();
+    chunker = undefined;
+}