@dash0/sdk-web 0.23.0 → 0.25.0

package/dist/types/instrumentations/session-recording/chunker.d.ts

@@ -0,0 +1,38 @@
+import { SessionRecordingEvent } from "../../types/session-recording";
+export type Chunk = {
+    /**
+     * Zero-based, monotonic within one recording.
+     */
+    seq: number;
+    /**
+     * The rrweb events as a serialized JSON array.
+     */
+    body: string;
+    eventCount: number;
+    hasSnapshot: boolean;
+    /**
+     * Milliseconds since the unix epoch of the first and the last event in the chunk.
+     */
+    startTime: number;
+    endTime: number;
+};
+export type ChunkerOptions = {
+    maxBytes: number;
+    maxMillis: number;
+    onChunk: (chunk: Chunk) => void;
+};
+export type Chunker = {
+    add(event: SessionRecordingEvent): void;
+    flush(): void;
+    /**
+     * Drops buffered events without emitting a chunk and cancels the pending time-based flush. Used when the
+     * recorder failed to start after it already emitted events, so no stray chunk is transmitted later.
+     */
+    discard(): void;
+};
+/**
+ * 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 declare function newChunker(opts: ChunkerOptions): Chunker;

package/dist/types/instrumentations/session-recording/chunker_test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/instrumentations/session-recording/index.d.ts

@@ -0,0 +1,23 @@
+import { SessionRecorder } from "../../types/session-recording";
+/**
+ * Global set by `dash0-session-recording.iife.js`. Read by `armSessionRecording()` and by
+ * `startSessionRecording()` when called without a recorder.
+ */
+export declare const GLOBAL_RECORDER_KEY = "dash0Recorder";
+/**
+ * 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 declare function registerSessionRecorder(r: SessionRecorder): void;
+/**
+ * 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 declare function armSessionRecording(): void;
+export declare function stopSessionRecording(): void;
+export declare function isSessionRecording(): boolean;

package/dist/types/instrumentations/session-recording/index_test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/instrumentations/session-recording/log.d.ts

@@ -0,0 +1,14 @@
+import { LogRecord } from "../../types/otlp";
+import { Chunk } from "./chunker";
+export type RecordingStream = {
+    /**
+     * Identifies one recorder run. All chunks of the run share it.
+     */
+    recordingId: string;
+    /**
+     * Trace context shared by all chunks of the run. The trace ID embeds the session ID.
+     */
+    traceId: string;
+    spanId: string;
+};
+export declare function buildSessionRecordingLog(stream: RecordingStream, chunk: Chunk): LogRecord;

package/dist/types/instrumentations/session-recording/log_test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/semantic-conventions.d.ts

@@ -23,6 +23,11 @@ export declare const WINDOW_WIDTH = "browser.window.width";
 export declare const WINDOW_HEIGHT = "browser.window.height";
 export declare const NETWORK_CONNECTION_TYPE = "network.connection.subtype";
 export declare const EXCEPTION_COMPONENT_STACK = "exception.component_stack";
+export declare const SESSION_RECORDING_ID = "dash0.session_recording.id";
+export declare const SESSION_RECORDING_SEQ = "dash0.session_recording.seq";
+export declare const SESSION_RECORDING_EVENT_COUNT = "dash0.session_recording.event_count";
+export declare const SESSION_RECORDING_HAS_SNAPSHOT = "dash0.session_recording.has_snapshot";
+export declare const SESSION_RECORDING_END_TIME_UNIX_NANO = "dash0.session_recording.end_time_unix_nano";
 export declare const USER_ID = "user.id";
 export declare const USER_NAME = "user.name";
 export declare const USER_FULL_NAME = "user.full_name";
@@ -51,6 +56,7 @@ export declare const EVENT_NAMES: {
     NAVIGATION_TIMING: string;
     WEB_VITAL: string;
     ERROR: string;
+    SESSION_RECORDING: string;
 };
 export declare const SPAN_EVENT_NAME_EXCEPTION = "exception";
 export declare const LOG_SEVERITIES: {

package/dist/types/transport/fetch.d.ts

@@ -1 +1,8 @@
-export declare function send(path: string, body: unknown): Promise<void>;
+export type SendOptions = {
+    /**
+     * Compress this request regardless of `vars.enableTransportCompression`. Used for payloads that are
+     * large and highly compressible, such as session recording chunks.
+     */
+    compress?: boolean;
+};
+export declare function send(path: string, body: unknown, opts?: SendOptions): Promise<void>;

package/dist/types/transport/index.d.ts

@@ -1,3 +1,13 @@
+import { SendOptions } from "./fetch";
 import { LogRecord, Span } from "../types/otlp";
 export declare function sendLog(log: LogRecord): void;
+/**
+ * Transmits a session recording chunk as a single log record. Chunks bypass the log batcher: batching 15 chunks
+ * of up to `chunkMaxBytes` each would produce requests far beyond the keepalive body limit.
+ *
+ * Chunks are gzipped by default because replay JSON compresses roughly 8:1. Pass `compress: false` when the
+ * request must be issued synchronously, i.e. while the document is being unloaded: compression is asynchronous
+ * and the page may be gone before `fetch()` is ever called.
+ */
+export declare function sendSessionRecordingChunk(log: LogRecord, opts?: SendOptions): void;
 export declare function sendSpan(span: Span | undefined): void;

package/dist/types/transport/index_test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/types/options.d.ts

@@ -1,7 +1,7 @@
 import { AttributeValueType } from "../utils/otel";
 import { AnyValue } from "./otlp";
 import { Endpoint, Vars, PropagatorConfig } from "../vars";
-export type InstrumentationName = "@dash0/navigation" | "@dash0/web-vitals" | "@dash0/error" | "@dash0/fetch" | "@dash0/xhr";
+export type InstrumentationName = "@dash0/navigation" | "@dash0/web-vitals" | "@dash0/error" | "@dash0/fetch" | "@dash0/xhr" | "@dash0/session-recording";
 /**
  * VCS (version control) context describing the build the SDK is running
  * inside. Used both as the public manual-override shape on `InitOptions.vcs`
@@ -110,4 +110,4 @@ export type InitOptions = {
      * Each propagator defines which header type to send for matching URLs.
      */
     propagators?: PropagatorConfig[];
-} & Partial<Pick<Vars, "ignoreUrls" | "ignoreErrorMessages" | "wrapEventHandlers" | "wrapTimers" | "propagateTraceHeadersCorsURLs" | "maxWaitForResourceTimingsMillis" | "maxToleranceForResourceTimingsMillis" | "headersToCapture" | "urlAttributeScrubber" | "pageViewInstrumentation" | "enableTransportCompression">>;
+} & Partial<Pick<Vars, "ignoreUrls" | "ignoreErrorMessages" | "wrapEventHandlers" | "wrapTimers" | "propagateTraceHeadersCorsURLs" | "maxWaitForResourceTimingsMillis" | "maxToleranceForResourceTimingsMillis" | "headersToCapture" | "urlAttributeScrubber" | "pageViewInstrumentation" | "sessionRecording" | "enableTransportCompression">>;

package/dist/types/types/session-recording.d.ts

@@ -0,0 +1,128 @@
+/**
+ * The subset of rrweb's `record()` option surface the SDK forwards. Declared structurally so the
+ * public API of `@dash0/sdk-web` does not depend on `@rrweb/types`; rrweb's `record` satisfies it.
+ */
+export type SessionRecorderOptions = {
+    /**
+     * Called by the recorder for every rrweb event. `isCheckout` is true for the events that
+     * start a new full snapshot (see `checkoutEveryNms`).
+     */
+    emit: (event: SessionRecordingEvent, isCheckout?: boolean) => void;
+    checkoutEveryNms?: number;
+    maskAllInputs?: boolean;
+    maskTextClass?: string | RegExp;
+    maskTextSelector?: string;
+    maskInputFn?: (text: string, element: HTMLElement | null) => string;
+    maskTextFn?: (text: string, element: HTMLElement | null) => string;
+    blockClass?: string | RegExp;
+    blockSelector?: string;
+    ignoreClass?: string;
+    recordCanvas?: boolean;
+    collectFonts?: boolean;
+    inlineStylesheet?: boolean;
+};
+/**
+ * A function that starts recording and returns a function that stops it.
+ * `record` from `@rrweb/record` (re-exported by `@dash0/sdk-web/session-recording`) has this shape.
+ */
+export type SessionRecorder = (options: SessionRecorderOptions) => (() => void) | undefined;
+/**
+ * The shape of an rrweb event the SDK relies on. rrweb events carry more data, which the SDK
+ * forwards untouched inside the chunk body.
+ */
+export type SessionRecordingEvent = {
+    /**
+     * rrweb EventType. 2 is FullSnapshot, 4 is Meta.
+     */
+    type: number;
+    /**
+     * Milliseconds since the unix epoch.
+     */
+    timestamp: number;
+    data?: unknown;
+};
+export type SessionRecordingSettings = {
+    /**
+     * The percentage of sessions for which a recording is captured. Must be a number between 0 and 100.
+     * The decision is deterministic per session ID and uses the same hash as `sessionSamplingRate`, so
+     * recorded sessions are always a subset of the sessions for which telemetry is transmitted.
+     *
+     * @default 100
+     */
+    samplingRate?: number;
+    /**
+     * Replace the value of every visible input, textarea and select with asterisks before it leaves the browser.
+     * `<input type="hidden">` values are element attributes and are not masked; use `blockSelector` for those.
+     * Set to `false` only when you know no form on the page accepts sensitive data.
+     *
+     * @default true
+     */
+    maskAllInputs?: boolean;
+    /**
+     * CSS selector for elements whose text content must be masked. Use `"*"` to mask all text on the page.
+     */
+    maskTextSelector?: string;
+    /**
+     * Elements with this class have their text content masked.
+     *
+     * @default "dash0-mask"
+     */
+    maskTextClass?: string | RegExp;
+    /**
+     * Elements with this class are not recorded at all. A placeholder with the same dimensions
+     * is shown in the replay instead.
+     *
+     * @default "dash0-block"
+     */
+    blockClass?: string | RegExp;
+    /**
+     * CSS selector for elements that are not recorded at all.
+     */
+    blockSelector?: string;
+    /**
+     * Custom function to mask input values. Receives the raw value and the element, and must return the masked value.
+     */
+    maskInputFn?: (text: string, element: HTMLElement | null) => string;
+    /**
+     * Custom function to mask text nodes. Receives the raw text and the parent element, and must return the masked text.
+     */
+    maskTextFn?: (text: string, element: HTMLElement | null) => string;
+    /**
+     * Record the content of canvas elements. This is expensive and off by default.
+     *
+     * @default false
+     */
+    recordCanvas?: boolean;
+    /**
+     * Collect fonts so the replay renders with the same typefaces. Adds payload size.
+     *
+     * @default false
+     */
+    collectFonts?: boolean;
+    /**
+     * The maximum serialized size of one chunk in bytes. When the buffered events reach this size, a chunk is
+     * transmitted. A single rrweb event larger than this (typically a full snapshot) is transmitted on its own.
+     *
+     * @default 48000
+     */
+    chunkMaxBytes?: number;
+    /**
+     * The maximum time buffered events wait before they are transmitted as a chunk.
+     *
+     * @default 5000
+     */
+    chunkMaxMillis?: number;
+    /**
+     * How often the recorder takes a new full snapshot of the DOM, in milliseconds. A replay can start
+     * from any chunk that contains a full snapshot.
+     *
+     * @default 300000
+     */
+    checkoutEveryNms?: number;
+    /**
+     * The recorder to use. Pass `recorder` from `@dash0/sdk-web/session-recording`. When omitted, the SDK waits for
+     * a recorder to be registered through `startSessionRecording(recorder)` or through the
+     * `dash0-session-recording.iife.js` script.
+     */
+    recorder?: SessionRecorder;
+};

package/dist/types/vars.d.ts

@@ -1,6 +1,7 @@
 import { AttributeValueType } from "./utils/otel";
 import { AnyValue, InstrumentationScope, KeyValue, Resource } from "./types/otlp";
 import { UrlAttributeScrubber } from "./attributes";
+import { SessionRecordingSettings } from "./types/session-recording";
 export type PropagatorType = "traceparent" | "xray";
 export type PropagatorConfig = {
     type: PropagatorType;
@@ -140,6 +141,11 @@ export type Vars = {
      */
     urlAttributeScrubber: UrlAttributeScrubber;
     pageViewInstrumentation: PageViewInstrumentationSettings;
+    /**
+     * Session recording (replay) settings. Recording only starts when a recorder is provided, either through
+     * `sessionRecording.recorder`, `startSessionRecording(recorder)`, or the `dash0-session-recording.iife.js` script.
+     */
+    sessionRecording: SessionRecordingSettings;
     /**
      * Enables telemetry transport compression using gzip.
      * experimental - in rare cases causes Chrome to crash to use at your own risk.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dash0/sdk-web",
-  "version": "0.23.0",
+  "version": "0.25.0",
   "description": "Dash0's Web SDK to collect telemetry from end-users' web browsers",
   "type": "module",
   "main": "dist/dash0.umd.cjs",
@@ -11,14 +11,20 @@
       "types": "./dist/types/entrypoint/npm-package.d.ts",
       "require": "./dist/dash0.umd.cjs",
       "default": "./dist/dash0.js"
+    },
+    "./session-recording": {
+      "types": "./dist/types/entrypoint/session-recording.d.ts",
+      "require": "./dist/dash0-session-recording.umd.cjs",
+      "default": "./dist/dash0-session-recording.js"
     }
   },
   "types": "./dist/types/entrypoint/npm-package.d.ts",
   "scripts": {
-    "build": "run-s build:clean build:typescript build:rollup build:stats",
+    "build": "run-s build:clean build:typescript build:rollup build:verify build:stats",
     "build:clean": "rm -rf dist",
     "build:typescript": "tsc -b",
     "build:rollup": "rollup -c -m",
+    "build:verify": "node scripts/verify-bundles.mjs",
     "build:stats": "echo \"\nFile Stats:\" && ls dist/*.js | xargs -I '%' bash -c 'echo \"%: $(./node_modules/.bin/gzip-size % --include-original) (gzip)\"'",
     "prettier:all": "prettier . --write --cache --list-different",
     "prettier:check": "prettier . --check",
@@ -29,6 +35,7 @@
     "test:unit:watch": "vitest",
     "test:e2e": "wdio run ./test/e2e/wdio.conf.ts",
     "test:e2e:local": "pnpm run build && wdio run ./test/e2e/wdio.local.conf.ts",
+    "sink": "node scripts/otlp-sink.mjs",
     "test:e2e:server": "SERVER_PORTS='8010,8011,8012' node test/e2e/server/index.mjs",
     "test:e2e:tunnel": "dotenv -- bash -c './.lambdatest/v3/LT --user $LT_USERNAME --key $LT_ACCESS_KEY'",
     "test:e2e:live": "run-p test:e2e:server test:e2e:tunnel",
@@ -71,6 +78,7 @@
     "web-vitals": "^5.0.3"
   },
   "devDependencies": {
+    "@rrweb/record": "^2.1.1",
     "@babel/core": "^7.26.10",
     "@babel/preset-env": "^7.26.9",
     "@release-it/conventional-changelog": "^10.0.1",
@@ -117,7 +125,7 @@
   "resolutions": {
     "conventional-changelog-conventionalcommits": "8.0.0"
   },
-  "packageManager": "pnpm@9.15.1",
+  "packageManager": "pnpm@10.33.4",
   "publishConfig": {
     "access": "public"
   }

package/src/api/init.ts

@@ -35,6 +35,7 @@ import { initializeTabId } from "../utils/tab-id";
 import { InitOptions, InstrumentationName } from "../types/options";
 import { BrowserBuildEnv, pickFirstString } from "./browser-env";
 import { applyVcsResourceAttributes } from "./vcs";
+import { armSessionRecording } from "../instrumentations/session-recording";
 
 declare const process: { env?: BrowserBuildEnv } | undefined;
 
@@ -86,6 +87,7 @@ export function init(opts: InitOptions) {
         "headersToCapture",
         "urlAttributeScrubber",
         "pageViewInstrumentation",
+        "sessionRecording",
         "enableTransportCompression",
       ])
     )
@@ -124,6 +126,9 @@ export function init(opts: InitOptions) {
   if (isInstrumentationEnabled("@dash0/xhr", opts)) {
     instrumentXhr();
   }
+  if (isInstrumentationEnabled("@dash0/session-recording", opts)) {
+    armSessionRecording();
+  }
 
   hasBeenInitialised = true;
 }
@@ -303,7 +308,10 @@ function merge<T extends Record<string, unknown>>(target: T, source: Partial<T>)
         dstVal !== null &&
         !Array.isArray(dstVal)
       ) {
-        result[key] = { ...dstVal, ...srcVal } as T[keyof T];
+        // 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 as Record<string, unknown>) } as T[keyof T];
       } else {
         result[key] = srcVal as T[keyof T];
       }
@@ -311,3 +319,13 @@ function merge<T extends Record<string, unknown>>(target: T, source: Partial<T>)
   }
   return result;
 }
+
+function withoutUndefined<T extends Record<string, unknown>>(obj: T): Partial<T> {
+  const result: Partial<T> = {};
+  for (const key of Object.keys(obj) as Array<keyof T>) {
+    if (obj[key] !== undefined) {
+      result[key] = obj[key];
+    }
+  }
+  return result;
+}

package/src/api/init_test.ts

@@ -38,6 +38,10 @@ 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");
@@ -52,6 +56,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: InitOptions = {
@@ -78,6 +83,31 @@ describe("init", () => {
     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({
@@ -98,13 +128,15 @@ describe("init", () => {
       "@dash0/error",
       "@dash0/fetch",
       "@dash0/xhr",
+      "@dash0/session-recording",
     ];
-    const instrumentationMocks = {
+    const instrumentationMocks: Record<InstrumentationName, () => void> = {
       "@dash0/navigation": startNavigationInstrumentation,
       "@dash0/web-vitals": startWebVitalsInstrumentation,
       "@dash0/error": startErrorInstrumentation,
       "@dash0/fetch": instrumentFetch,
       "@dash0/xhr": instrumentXhr,
+      "@dash0/session-recording": armSessionRecording,
     };
 
     instrumentations.forEach((instrumentation) => {

package/src/api/session-recording.ts

@@ -0,0 +1,40 @@
+import { debug, win } from "../utils";
+import { SessionRecorder } from "../types/session-recording";
+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?: SessionRecorder): void {
+  // 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 as any)?.[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 as SessionRecorder);
+}
+
+/**
+ * Stops the running session recording and transmits any buffered events. Calling this when no recording is
+ * running is a no-op.
+ */
+export function stopSessionRecording(): void {
+  stopRecording();
+}

package/src/api/session-recording_test.ts

@@ -0,0 +1,44 @@
+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 as any;
+
+describe("startSessionRecording api", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    delete globalObject.dash0Recorder;
+  });
+
+  it("registers an explicitly passed recorder", () => {
+    const recorder = vi.fn();
+    startSessionRecording(recorder as any);
+    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" as any)).not.toThrow();
+    expect(registerSessionRecorder).not.toHaveBeenCalled();
+  });
+
+  it("delegates stop", () => {
+    stopSessionRecording();
+    expect(stopImpl).toHaveBeenCalledTimes(1);
+  });
+});

package/src/api/start-view.ts

@@ -0,0 +1,68 @@
+import { transmitManualPageViewEvent } from "../instrumentations/navigation/event";
+import { AttributeValueType } from "../utils/otel";
+import { AnyValue } from "../types/otlp";
+import { debug, nowNanos, win } from "../utils";
+import { vars } from "../vars";
+
+export type StartViewOptions = {
+  /**
+   * Optionally override the url reflected in `page.url.*` attributes for this view.
+   * Accepts an absolute or relative url; relative urls are resolved against the current
+   * `location.href`. Falls back to the real `location.href` if omitted or invalid.
+   * This is display-only: calling startView never navigates or mutates history/location.
+   */
+  url?: string;
+
+  /**
+   * Additional attributes to include with the page view.
+   * Added after the SDK-generated attributes, so they can override them.
+   */
+  attributes?: Record<string, AttributeValueType | AnyValue>;
+};
+
+/**
+ * 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: string, opts?: StartViewOptions) {
+  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: URL | undefined;
+  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,
+  });
+}