@groundcover/browser 2.0.0 → 2.1.0-rc.0

package/CHANGELOG.md

@@ -4,6 +4,31 @@ All notable changes to `@groundcover/browser` are documented here. This project
 [Semantic Versioning](https://semver.org/spec/v2.0.0.html) and the
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) format.
 
+## [2.1.0-rc.0] — 2026-10-06
+
+First release candidate of `2.1.0`, on top of `2.0.0`. Adds opt-in canvas capture to session replay;
+nothing changes unless `options.replay.canvas.enabled` is set.
+
+### Added
+
+- **Session replay can capture `<canvas>`-rendered content** (e.g. chart data series that replayed
+  as empty frames) via `options.replay.canvas`. Off by default. `enabled` maps to rrweb
+  `recordCanvas`, `fps` (default 4, clamped to 1–15 with a warning) to `sampling.canvas`, and
+  `imageType` / `imageQuality` (default `image/webp` at 0.6) to `dataURLOptions`. Canvas frames are
+  pixel snapshots: they increase replay bandwidth and page CPU, and are **not** covered by `privacy`
+  text/input masking. WebGL capture is best-effort only (the page's context must use
+  `preserveDrawingBuffer: true`).
+- **Changing `replay.canvas` through `updateConfig` restarts the active recording**, like
+  `replay.blockedSelectors` and `privacy`. A partial update merges into the current canvas options,
+  so `{ canvas: { fps: 8 } }` keeps capture enabled.
+
+### Fixed
+
+- **rrweb recorder errors stay inside the SDK.** Observer failures that fire after `record()`
+  returns are routed through the SDK's error handler instead of reaching the host page.
+- **`updateConfig` restarts the recording only for keys the update itself sets.** An inherited
+  (non-own) `privacy` or `replay` key no longer splits the recording without changing the config.
+
 ## [2.0.0] — 2026-10-06
 
 Stable release of the `2.0.0-rc.0` and `2.0.0-rc.1` line. **Contains breaking changes from `1.x`** —

package/README.md

@@ -179,17 +179,68 @@ content use [`privacy`](#privacy--data-masking).
 | Option | Type | Default | Description |
 |---|---|---|---|
 | `blockedSelectors` | `string[]` | — | CSS selectors whose elements (and subtrees) are excluded from recording. Useful for noisy extension-injected DOM (e.g. Grammarly). |
+| `canvas` | `ReplayCanvasOptions` | off | **Opt-in** capture of `<canvas>`-rendered content (charts, WebGL widgets). Off by default — see [Canvas capture](#canvas-capture-opt-in) for the fields and tradeoffs. |
 
 > ⚠️ Don’t confuse `options.replay.blockedSelectors` (recording noise reduction) with
 > `options.privacy.replay.*` (rrweb masking callbacks). They live at different levels and serve
 > different purposes.
 
+#### Canvas capture (opt-in)
+
+By default rrweb only serializes the DOM/SVG around a `<canvas>`, so anything **drawn to a canvas**
+— chart data series, WebGL scenes — is **not** recorded and replays as an empty frame. Set
+`options.replay.canvas.enabled` to capture canvas pixels as periodic image snapshots.
+
+```ts
+groundcover.init({
+  // …
+  options: {
+    enabledEvents: ["replay" /* … */],
+    replay: {
+      canvas: {
+        enabled: true,        // default false
+        fps: 4,               // default 4, clamped to [1, 15]
+        imageType: "image/webp", // default 'image/webp' ('image/jpeg' | 'image/png')
+        imageQuality: 0.6,    // default 0.6 (lossy formats only)
+      },
+    },
+  },
+});
+```
+
+| Field | Type | Default | Maps to rrweb |
+|---|---|---|---|
+| `enabled` | `boolean` | `false` | `recordCanvas` |
+| `fps` | `number` | `4` (clamped `[1, 15]`) | `sampling.canvas` |
+| `imageType` | `'image/webp' \| 'image/jpeg' \| 'image/png'` | `'image/webp'` | `dataURLOptions.type` |
+| `imageQuality` | `number` (0–1) | `0.6` | `dataURLOptions.quality` |
+
+> ⚠️ **Canvas capture is expensive and off by default for good reason.** Enable it only when you
+> knowingly accept the tradeoffs:
+> - **Bandwidth** — every snapshot is a serialized image, so replay payloads grow substantially on
+>   canvas-heavy pages. Keep `fps` low and prefer lossy `image/webp`/`image/jpeg`.
+> - **CPU** — snapshotting runs on the recorded (end-user) page and adds work to a busy dashboard.
+> - **Privacy** — canvas pixels **bypass `privacy` text/input masking entirely**. Whatever is drawn
+>   is captured verbatim; do not enable canvas capture on views that render sensitive data to a
+>   canvas.
+
+> **WebGL:** capture is **best-effort and not officially supported** by this option. Snapshotting a
+> WebGL/WebGL2 canvas only yields pixels if the page created its context with
+> `preserveDrawingBuffer: true`; otherwise frames may come back blank. 2D canvases (the common chart
+> case) are captured reliably.
+
+Changing `replay.canvas` (or `replay.blockedSelectors`) via `updateConfig` restarts the active
+recording so the new options take effect at rrweb `record()` time. A partial `canvas` update merges
+into the current one, so `{ canvas: { fps: 8 } }` keeps capture enabled; pass `enabled: false` to
+turn it off.
+
 ### Updating config at runtime
 
 `updateConfig` accepts these optional fields: `cluster`, `environment`, `namespace`, `releaseId`,
 `dsn`, `apiKey`, `options`, and `user`. `appId` cannot be updated. `sessionId` is not accepted;
-use the separate `setSessionId()` API. Nested groups merge one level deep (and `tracing.origin` /
-`privacy.replay` one level deeper), so a partial update preserves the other keys in the group:
+use the separate `setSessionId()` API. Nested groups merge one level deep (and `tracing.origin`,
+`privacy.replay` and `replay.canvas` one level deeper), so a partial update preserves the other keys in
+the group:
 
 ```ts
 groundcover.updateConfig({
@@ -320,6 +371,7 @@ record-time masking from your [`privacy`](#privacy--data-masking) config:
 - `privacy.level` / `privacy.maskSelectors` → rrweb `maskAllInputs` + `maskTextSelector`
 - `privacy.replay.maskTextFn` / `maskInputFn` → rrweb `maskTextFn` / `maskInputFn`
 - `options.replay.blockedSelectors` → rrweb `blockSelector` (noise reduction)
+- `options.replay.canvas` → rrweb `recordCanvas` + `sampling.canvas` + `dataURLOptions` (opt-in, off by default — see [Canvas capture](#canvas-capture-opt-in))
 
 Replay recording does **not** start automatically — even when `replay` is in `enabledEvents`. You
 must start it explicitly (e.g. after obtaining user consent):

package/dist/index.d.mts

@@ -324,6 +324,44 @@ type EventTypes = {
 };
 /** The browser SDK's listener names for `enabledEvents`. */
 type BrowserEventName = "dom" | "network" | "exceptions" | "logs" | "pageload" | "navigation" | "performance" | "replay";
+/**
+ * Opt-in canvas capture for session replay. Charts and other `<canvas>`-drawn
+ * content (2D or WebGL) are NOT recorded by default; rrweb only serializes the
+ * DOM/SVG around them, so canvas-rendered data series replay as empty frames.
+ * Enabling this makes rrweb snapshot canvas pixels.
+ *
+ * ⚠️ HIGH COST — off by default for good reason:
+ * - Bandwidth: canvas frames serialize as images, inflating replay payloads.
+ * - CPU: snapshotting canvases is costly on the recorded (customer) page.
+ * - Privacy: canvas pixels bypass text/input masking entirely — whatever is
+ *   drawn is captured verbatim, regardless of the `privacy` config.
+ */
+interface ReplayCanvasOptions {
+    /**
+     * Enable canvas capture. Defaults to `false` (canvas is not recorded). Maps
+     * to rrweb's `recordCanvas`.
+     */
+    enabled?: boolean;
+    /**
+     * Snapshot frame rate, in frames per second. Defaults to 4 and is clamped to
+     * [1, 15]; out-of-range values are clamped with a `console.warn`. Maps to
+     * rrweb's `sampling.canvas`. Higher values mean smoother playback but larger
+     * payloads and more CPU.
+     */
+    fps?: number;
+    /**
+     * Image format for canvas snapshots. Defaults to `'image/webp'` (much smaller
+     * than rrweb's default lossless `image/png`). Maps to rrweb
+     * `dataURLOptions.type`.
+     */
+    imageType?: "image/webp" | "image/jpeg" | "image/png";
+    /**
+     * Lossy compression quality in [0, 1] for `image/webp` / `image/jpeg`.
+     * Defaults to 0.6 (ignored for `image/png`). Maps to rrweb
+     * `dataURLOptions.quality`.
+     */
+    imageQuality?: number;
+}
 /**
  * Session-replay (rrweb) recording controls. This is NOT a privacy surface —
  * to mask sensitive content use `privacy`.
@@ -339,6 +377,12 @@ interface ReplayOptions {
      * sensitive content use `privacy` instead.
      */
     blockedSelectors?: string[];
+    /**
+     * Opt-in canvas capture (chart data series, WebGL-backed widgets). Off by
+     * default. Capturing canvas is bandwidth-, CPU-, and privacy-sensitive — see
+     * {@link ReplayCanvasOptions}.
+     */
+    canvas?: ReplayCanvasOptions;
 }
 /** Session-recording (rrweb replay) masking — the only place replay can be masked. */
 interface ReplayMaskingOptions {
@@ -369,8 +413,8 @@ interface SDKOptions extends Omit<SDKOptions$1, "privacy" | "enabledEvents" | "b
      */
     privacy?: PrivacyOptions;
     /**
-     * Session-replay recording controls (noise reduction). For replay MASKING use
-     * `privacy` instead. See {@link ReplayOptions}.
+     * Session-replay recording controls (noise reduction, opt-in canvas capture).
+     * For replay MASKING use `privacy` instead. See {@link ReplayOptions}.
      */
     replay?: ReplayOptions;
 }

package/dist/index.d.ts

@@ -324,6 +324,44 @@ type EventTypes = {
 };
 /** The browser SDK's listener names for `enabledEvents`. */
 type BrowserEventName = "dom" | "network" | "exceptions" | "logs" | "pageload" | "navigation" | "performance" | "replay";
+/**
+ * Opt-in canvas capture for session replay. Charts and other `<canvas>`-drawn
+ * content (2D or WebGL) are NOT recorded by default; rrweb only serializes the
+ * DOM/SVG around them, so canvas-rendered data series replay as empty frames.
+ * Enabling this makes rrweb snapshot canvas pixels.
+ *
+ * ⚠️ HIGH COST — off by default for good reason:
+ * - Bandwidth: canvas frames serialize as images, inflating replay payloads.
+ * - CPU: snapshotting canvases is costly on the recorded (customer) page.
+ * - Privacy: canvas pixels bypass text/input masking entirely — whatever is
+ *   drawn is captured verbatim, regardless of the `privacy` config.
+ */
+interface ReplayCanvasOptions {
+    /**
+     * Enable canvas capture. Defaults to `false` (canvas is not recorded). Maps
+     * to rrweb's `recordCanvas`.
+     */
+    enabled?: boolean;
+    /**
+     * Snapshot frame rate, in frames per second. Defaults to 4 and is clamped to
+     * [1, 15]; out-of-range values are clamped with a `console.warn`. Maps to
+     * rrweb's `sampling.canvas`. Higher values mean smoother playback but larger
+     * payloads and more CPU.
+     */
+    fps?: number;
+    /**
+     * Image format for canvas snapshots. Defaults to `'image/webp'` (much smaller
+     * than rrweb's default lossless `image/png`). Maps to rrweb
+     * `dataURLOptions.type`.
+     */
+    imageType?: "image/webp" | "image/jpeg" | "image/png";
+    /**
+     * Lossy compression quality in [0, 1] for `image/webp` / `image/jpeg`.
+     * Defaults to 0.6 (ignored for `image/png`). Maps to rrweb
+     * `dataURLOptions.quality`.
+     */
+    imageQuality?: number;
+}
 /**
  * Session-replay (rrweb) recording controls. This is NOT a privacy surface —
  * to mask sensitive content use `privacy`.
@@ -339,6 +377,12 @@ interface ReplayOptions {
      * sensitive content use `privacy` instead.
      */
     blockedSelectors?: string[];
+    /**
+     * Opt-in canvas capture (chart data series, WebGL-backed widgets). Off by
+     * default. Capturing canvas is bandwidth-, CPU-, and privacy-sensitive — see
+     * {@link ReplayCanvasOptions}.
+     */
+    canvas?: ReplayCanvasOptions;
 }
 /** Session-recording (rrweb replay) masking — the only place replay can be masked. */
 interface ReplayMaskingOptions {
@@ -369,8 +413,8 @@ interface SDKOptions extends Omit<SDKOptions$1, "privacy" | "enabledEvents" | "b
      */
     privacy?: PrivacyOptions;
     /**
-     * Session-replay recording controls (noise reduction). For replay MASKING use
-     * `privacy` instead. See {@link ReplayOptions}.
+     * Session-replay recording controls (noise reduction, opt-in canvas capture).
+     * For replay MASKING use `privacy` instead. See {@link ReplayOptions}.
      */
     replay?: ReplayOptions;
 }