@dash0/sdk-web 0.23.0 → 0.25.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,30 @@
+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.
+ */
+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.
+ */
+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/api/start-view.js

@@ -0,0 +1,47 @@
+import { transmitManualPageViewEvent } from "../instrumentations/navigation/event";
+import { debug, nowNanos, win } from "../utils";
+import { vars } from "../vars";
+/**
+ * Manually records a page view, side-effect free: this never calls `history.pushState` /
+ * `history.replaceState` and never mutates `location`. Intended for single-page applications
+ * that own their own router and cannot let the SDK touch navigation state (e.g. Electron apps
+ * serving the whole app from one root URL, where automatic page-view tracking would report
+ * every screen as "/").
+ *
+ * The emitted event is indistinguishable from an automatic virtual page view downstream
+ * (same `browser.page_view` event name, same `type` value), with two differences: it is never
+ * accompanied by a `change_state` value, since no history mutation occurred, and the
+ * `pageViewInstrumentation`'s `generateMetadata` callback is not invoked for manual views —
+ * supply title and attributes directly instead.
+ *
+ * @param name The name of the view, e.g. "/settings". Transmitted as the page view's title.
+ * @param opts Additional page view details.
+ */
+export function startView(name, opts) {
+    if (vars.endpoints.length === 0) {
+        debug("Dash0 SDK has not been initialized. Ignoring startView call.");
+        return;
+    }
+    // The script entrypoint forwards dash0("startView", ...) 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.
+    if (typeof name !== "string" || name.length === 0) {
+        debug("startView requires a non-empty view name. Ignoring startView call.");
+        return;
+    }
+    let url;
+    if (opts?.url != null) {
+        try {
+            url = new URL(opts.url, win?.location.href);
+        }
+        catch (e) {
+            debug("Failed to parse startView url option. Falling back to the current location.", e);
+        }
+    }
+    transmitManualPageViewEvent({
+        timeUnixNano: nowNanos(),
+        title: name,
+        url,
+        attributes: opts?.attributes,
+    });
+}

package/dist/modules/api/start-view_test.js

@@ -0,0 +1,91 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+vi.mock("../transport", () => ({
+    sendLog: vi.fn(),
+}));
+import { sendLog } from "../transport";
+import { startView } from "./start-view";
+import { vars } from "../vars";
+const sendLogMock = sendLog;
+describe("startView", () => {
+    beforeEach(() => {
+        sendLogMock.mockClear();
+        vars.endpoints = [{ url: "https://example.com", authToken: "auth_abc123" }];
+        vars.pageViewInstrumentation = { trackVirtualPageViews: true, includeParts: [] };
+    });
+    afterEach(() => {
+        vi.clearAllMocks();
+        vars.endpoints = [];
+    });
+    it("accepts a string shorthand and uses it as the title", () => {
+        startView("/settings");
+        expect(sendLogMock).toHaveBeenCalledTimes(1);
+        const log = sendLogMock.mock.calls[0][0];
+        const bodyValues = log.body?.kvlistValue?.values;
+        expect(bodyValues).toEqual(expect.arrayContaining([{ key: "title", value: { stringValue: "/settings" } }]));
+    });
+    it("accepts an options object with attributes", () => {
+        startView("/settings", { attributes: { "app.screen": "settings" } });
+        const log = sendLogMock.mock.calls[0][0];
+        const bodyValues = log.body?.kvlistValue?.values;
+        expect(bodyValues).toEqual(expect.arrayContaining([{ key: "title", value: { stringValue: "/settings" } }]));
+        expect(log.attributes).toEqual(expect.arrayContaining([{ key: "app.screen", value: { stringValue: "settings" } }]));
+    });
+    it("parses a relative url option and reflects it in page.url.path", () => {
+        startView("/settings", { url: "/settings" });
+        const log = sendLogMock.mock.calls[0][0];
+        expect(log.attributes).toEqual(expect.arrayContaining([{ key: "page.url.path", value: { stringValue: "/settings" } }]));
+    });
+    it("falls back to the current location on an invalid url", () => {
+        startView("/settings", { url: "http://" });
+        expect(sendLogMock).toHaveBeenCalledTimes(1);
+        const log = sendLogMock.mock.calls[0][0];
+        expect(log.attributes).toEqual(expect.arrayContaining([
+            // eslint-disable-next-line no-restricted-globals
+            { key: "page.url.full", value: { stringValue: window.location.href } },
+            // eslint-disable-next-line no-restricted-globals
+            { key: "page.url.domain", value: { stringValue: window.location.hostname } },
+        ]));
+    });
+    it("resolves an absolute cross-origin url override", () => {
+        startView("/settings", { url: "https://other-origin.example/path" });
+        const log = sendLogMock.mock.calls[0][0];
+        expect(log.attributes).toEqual(expect.arrayContaining([
+            { key: "page.url.full", value: { stringValue: "https://other-origin.example/path" } },
+            { key: "page.url.domain", value: { stringValue: "other-origin.example" } },
+            { key: "page.url.path", value: { stringValue: "/path" } },
+        ]));
+    });
+    it("does not touch history or location", () => {
+        // eslint-disable-next-line no-restricted-globals
+        const originalHref = window.location.href;
+        // eslint-disable-next-line no-restricted-globals
+        const originalLength = window.history.length;
+        startView("/settings");
+        // eslint-disable-next-line no-restricted-globals
+        expect(window.location.href).toBe(originalHref);
+        // eslint-disable-next-line no-restricted-globals
+        expect(window.history.length).toBe(originalLength);
+    });
+    it("ignores calls without a name, as they can arrive via the untyped script entrypoint", () => {
+        // @ts-expect-error deliberately calling without arguments, mirroring dash0("startView")
+        startView();
+        startView(undefined);
+        startView(null);
+        expect(sendLogMock).not.toHaveBeenCalled();
+    });
+    it("ignores calls with a non-string or empty name", () => {
+        startView(123);
+        startView({ name: "/settings" });
+        startView("");
+        expect(sendLogMock).not.toHaveBeenCalled();
+    });
+    it("tolerates a nullish options argument", () => {
+        startView("/settings", null);
+        expect(sendLogMock).toHaveBeenCalledTimes(1);
+    });
+    it("is a no-op before init (no endpoints configured)", () => {
+        vars.endpoints = [];
+        startView("/settings");
+        expect(sendLogMock).not.toHaveBeenCalled();
+    });
+});

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

@@ -7,6 +7,8 @@ export * from "../api/events";
 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/npm-package_test.js

@@ -0,0 +1,7 @@
+import { describe, expect, it } from "vitest";
+import * as npmPackage from "./npm-package";
+describe("npm-package entrypoint", () => {
+    it("exports startView", () => {
+        expect(typeof npmPackage.startView).toBe("function");
+    });
+});

package/dist/modules/entrypoint/script.js

@@ -7,6 +7,8 @@ import { terminateSession } from "../api/session";
 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}}')`
  */
@@ -20,6 +22,9 @@ const scriptApis = {
     removeSignalAttribute,
     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/navigation/event.js

@@ -1,4 +1,4 @@
-import { addAttribute, getTraceContextForPageLoad } from "../../utils/otel";
+import { addAttribute, addAttributes, getTraceContextForPageLoad } from "../../utils/otel";
 import { EVENT_NAME, EVENT_NAMES, LOG_SEVERITIES, PAGE_VIEW_CHANGE_STATE, PAGE_VIEW_CHANGE_STATE_VALUES, PAGE_VIEW_TYPE, PAGE_VIEW_TYPE_VALUES, } from "../../semantic-conventions";
 import { doc, NO_VALUE_FALLBACK } from "../../utils";
 import { addCommonAttributes } from "../../attributes";
@@ -9,23 +9,26 @@ function getPageViewMeta(url) {
         return {};
     return vars.pageViewInstrumentation.generateMetadata?.(url) ?? {};
 }
-export function transmitPageViewEvent(timeUnixNano, url, virtual, replaced) {
-    const meta = getPageViewMeta(url);
+function buildAndSendPageViewLog(opts) {
     const attributes = [];
     addAttribute(attributes, EVENT_NAME, EVENT_NAMES.PAGE_VIEW);
-    if (meta.attributes) {
-        Object.entries(meta.attributes).forEach(([key, value]) => addAttribute(attributes, key, value));
+    if (opts.metaAttributes) {
+        Object.entries(opts.metaAttributes).forEach(([key, value]) => addAttribute(attributes, key, value));
     }
-    addCommonAttributes(attributes, { url });
+    addCommonAttributes(attributes, { url: opts.url });
+    // Add custom attributes last to allow overrides
+    addAttributes(attributes, opts.customAttributes);
     const bodyAttributes = [];
-    addAttribute(bodyAttributes, "title", meta.title ?? doc?.title ?? NO_VALUE_FALLBACK);
+    addAttribute(bodyAttributes, "title", opts.title ?? doc?.title ?? NO_VALUE_FALLBACK);
     if (doc?.referrer) {
         addAttribute(bodyAttributes, "referrer", doc.referrer);
     }
-    addAttribute(bodyAttributes, PAGE_VIEW_TYPE, virtual ? PAGE_VIEW_TYPE_VALUES.VIRTUAL : PAGE_VIEW_TYPE_VALUES.INITIAL);
-    addAttribute(bodyAttributes, PAGE_VIEW_CHANGE_STATE, replaced ? PAGE_VIEW_CHANGE_STATE_VALUES.REPLACE : PAGE_VIEW_CHANGE_STATE_VALUES.PUSH);
+    addAttribute(bodyAttributes, PAGE_VIEW_TYPE, opts.pageViewType);
+    if (opts.changeState) {
+        addAttribute(bodyAttributes, PAGE_VIEW_CHANGE_STATE, opts.changeState);
+    }
     const log = {
-        timeUnixNano: timeUnixNano,
+        timeUnixNano: opts.timeUnixNano,
         attributes: attributes,
         severityNumber: LOG_SEVERITIES.INFO,
         severityText: "INFO",
@@ -42,3 +45,32 @@ export function transmitPageViewEvent(timeUnixNano, url, virtual, replaced) {
     }
     sendLog(log);
 }
+export function transmitPageViewEvent(timeUnixNano, url, virtual, replaced) {
+    const meta = getPageViewMeta(url);
+    buildAndSendPageViewLog({
+        timeUnixNano,
+        url,
+        title: meta.title,
+        metaAttributes: meta.attributes,
+        pageViewType: virtual ? PAGE_VIEW_TYPE_VALUES.VIRTUAL : PAGE_VIEW_TYPE_VALUES.INITIAL,
+        changeState: replaced ? PAGE_VIEW_CHANGE_STATE_VALUES.REPLACE : PAGE_VIEW_CHANGE_STATE_VALUES.PUSH,
+    });
+}
+/**
+ * Emits a manually-triggered page view log, e.g. from the public `startView` API.
+ * Deliberately does NOT read `vars.pageViewInstrumentation.generateMetadata` and does NOT
+ * include a `change_state` body key (a manual view is neither a pushState nor replaceState).
+ * The emitted `type` is PAGE_VIEW_TYPE_VALUES.VIRTUAL, matching automatic virtual page views —
+ * manual views are deliberately indistinguishable from virtual ones downstream.
+ * Caller-provided attributes are added after the SDK-generated ones so they can override them,
+ * matching the sendEvent semantics.
+ */
+export function transmitManualPageViewEvent(opts) {
+    buildAndSendPageViewLog({
+        timeUnixNano: opts.timeUnixNano,
+        url: opts.url,
+        title: opts.title,
+        customAttributes: opts.attributes,
+        pageViewType: PAGE_VIEW_TYPE_VALUES.VIRTUAL,
+    });
+}

package/dist/modules/instrumentations/navigation/event_test.js

@@ -0,0 +1,128 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+vi.mock("../../transport", () => ({
+    sendLog: vi.fn(),
+}));
+import { sendLog } from "../../transport";
+import { transmitPageViewEvent, transmitManualPageViewEvent } from "./event";
+import { vars } from "../../vars";
+const sendLogMock = sendLog;
+describe("transmitPageViewEvent", () => {
+    beforeEach(() => {
+        sendLogMock.mockClear();
+        vars.pageViewInstrumentation = { trackVirtualPageViews: true, includeParts: [] };
+    });
+    afterEach(() => {
+        vi.clearAllMocks();
+    });
+    it("transmits an initial page view with type=INITIAL and change_state=pushState", () => {
+        transmitPageViewEvent("1700000000000000000", new URL("https://example.com/landing"));
+        expect(sendLogMock).toHaveBeenCalledTimes(1);
+        const log = sendLogMock.mock.calls[0][0];
+        expect(log.timeUnixNano).toBe("1700000000000000000");
+        expect(log.severityNumber).toBe(9);
+        expect(log.severityText).toBe("INFO");
+        expect(log.attributes).toEqual(expect.arrayContaining([{ key: "event.name", value: { stringValue: "browser.page_view" } }]));
+        const bodyValues = log.body?.kvlistValue?.values;
+        expect(bodyValues).toEqual(expect.arrayContaining([
+            { key: "type", value: { doubleValue: 0 } },
+            { key: "change_state", value: { stringValue: "pushState" } },
+        ]));
+    });
+    it("transmits a virtual page view with type=VIRTUAL and change_state=replaceState when replaced", () => {
+        transmitPageViewEvent("1700000000000000000", new URL("https://example.com/settings"), true, true);
+        const log = sendLogMock.mock.calls[0][0];
+        const bodyValues = log.body?.kvlistValue?.values;
+        expect(bodyValues).toEqual(expect.arrayContaining([
+            { key: "type", value: { doubleValue: 1 } },
+            { key: "change_state", value: { stringValue: "replaceState" } },
+        ]));
+    });
+    it("applies generateMetadata title and attributes when provided", () => {
+        vars.pageViewInstrumentation = {
+            trackVirtualPageViews: true,
+            includeParts: [],
+            generateMetadata: () => ({ title: "Custom Title", attributes: { "app.screen": "settings" } }),
+        };
+        transmitPageViewEvent("1700000000000000000", new URL("https://example.com/settings"), true);
+        const log = sendLogMock.mock.calls[0][0];
+        expect(log.attributes).toEqual(expect.arrayContaining([{ key: "app.screen", value: { stringValue: "settings" } }]));
+        const bodyValues = log.body?.kvlistValue?.values;
+        expect(bodyValues).toEqual(expect.arrayContaining([{ key: "title", value: { stringValue: "Custom Title" } }]));
+    });
+});
+describe("transmitManualPageViewEvent", () => {
+    beforeEach(() => {
+        sendLogMock.mockClear();
+        vars.pageViewInstrumentation = {
+            trackVirtualPageViews: true,
+            includeParts: [],
+            generateMetadata: () => ({ title: "should not be used", attributes: { should_not_appear: true } }),
+        };
+    });
+    afterEach(() => {
+        vi.clearAllMocks();
+        vars.pageViewInstrumentation = { trackVirtualPageViews: true, includeParts: [] };
+    });
+    it("emits type=VIRTUAL and no change_state key", () => {
+        transmitManualPageViewEvent({ timeUnixNano: "1700000000000000000", title: "/settings" });
+        const log = sendLogMock.mock.calls[0][0];
+        const bodyValues = log.body?.kvlistValue?.values;
+        expect(bodyValues).toEqual(expect.arrayContaining([
+            { key: "type", value: { doubleValue: 1 } },
+            { key: "title", value: { stringValue: "/settings" } },
+        ]));
+        expect(bodyValues.find((v) => v.key === "change_state")).toBeUndefined();
+    });
+    it("does not invoke vars.pageViewInstrumentation.generateMetadata", () => {
+        const generateMetadata = vi.fn().mockReturnValue({ title: "ignored" });
+        vars.pageViewInstrumentation = { trackVirtualPageViews: true, includeParts: [], generateMetadata };
+        transmitManualPageViewEvent({ timeUnixNano: "1700000000000000000", title: "/settings" });
+        expect(generateMetadata).not.toHaveBeenCalled();
+        const log = sendLogMock.mock.calls[0][0];
+        const bodyValues = log.body?.kvlistValue?.values;
+        expect(bodyValues).toEqual(expect.arrayContaining([{ key: "title", value: { stringValue: "/settings" } }]));
+    });
+    it("merges custom attributes into signal attributes", () => {
+        transmitManualPageViewEvent({
+            timeUnixNano: "1700000000000000000",
+            title: "/settings",
+            attributes: { "app.screen": "settings", "app.tab_index": 2 },
+        });
+        const log = sendLogMock.mock.calls[0][0];
+        expect(log.attributes).toEqual(expect.arrayContaining([
+            { key: "app.screen", value: { stringValue: "settings" } },
+            { key: "app.tab_index", value: { doubleValue: 2 } },
+        ]));
+    });
+    it("adds custom attributes after SDK-generated ones so they can override", () => {
+        transmitManualPageViewEvent({
+            timeUnixNano: "1700000000000000000",
+            title: "/settings",
+            url: new URL("https://example.com/real-path"),
+            attributes: { "page.url.path": "/custom-path" },
+        });
+        const log = sendLogMock.mock.calls[0][0];
+        const pathAttributes = log.attributes.filter((attr) => attr.key === "page.url.path");
+        expect(pathAttributes.length).toBeGreaterThan(1);
+        expect(pathAttributes[pathAttributes.length - 1]).toEqual({
+            key: "page.url.path",
+            value: { stringValue: "/custom-path" },
+        });
+    });
+    it("passes url through to page.url.* attributes when provided", () => {
+        transmitManualPageViewEvent({
+            timeUnixNano: "1700000000000000000",
+            title: "/settings",
+            url: new URL("https://example.com/settings"),
+        });
+        const log = sendLogMock.mock.calls[0][0];
+        expect(log.attributes).toEqual(expect.arrayContaining([{ key: "page.url.path", value: { stringValue: "/settings" } }]));
+    });
+    it("includes referrer the same way the auto path does", () => {
+        transmitManualPageViewEvent({ timeUnixNano: "1700000000000000000", title: "/settings" });
+        const log = sendLogMock.mock.calls[0][0];
+        const bodyValues = log.body?.kvlistValue?.values;
+        // doc.referrer is empty string in jsdom by default, so "referrer" key should be absent
+        expect(bodyValues.find((v) => v.key === "referrer")).toBeUndefined();
+    });
+});

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);
+    }
+}