@groundcover/browser 2.0.0 → 2.1.0-rc.1

package/CHANGELOG.md

@@ -4,6 +4,45 @@ 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.1] — 2026-10-07
+
+Second release candidate of `2.1.0`. Tunes canvas capture's default from measurements; nothing
+changes unless `options.replay.canvas.enabled` is set.
+
+### Changed
+
+- **`replay.canvas.fps` defaults to 1** (was 4). rrweb re-encodes every canvas on every tick whether
+  or not it changed, so the rate drives CPU even on a static page, while bytes grow only when content
+  changes. On a six-chart test dashboard, 1 fps used about 12% of a CPU core against about 35% at
+  4 fps, with the same bytes. Set `fps` explicitly for animated canvases.
+- **README: canvas capture recipes** for dashboards, animated canvases, constrained bandwidth and
+  CPU-sensitive pages, with measured costs for scale.
+
+## [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,86 @@ 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: 1,               // default 1, 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` | `1` (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** — every canvas on the page is re-encoded every `1/fps` seconds, changed or not, on the
+>   recorded (end-user) device. `fps` is the main CPU lever.
+> - **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.
+
+##### Recipes
+
+Canvas capture's cost depends on the page: how many canvases, how big they are, and how often they
+redraw. Start from the closest recipe and adjust:
+
+| Page | Config | Why |
+|---|---|---|
+| Dashboards and charts that redraw every few seconds or on interaction | `{ enabled: true }` | The 1 fps default costs the least CPU, and charts that change slower than once a second send the same bytes at any rate. |
+| Animated canvases (live charts, maps, games) | `{ enabled: true, fps: 4, imageQuality: 0.4 }` | Smoother playback. Every changed canvas sends a full image per frame, so bytes grow with `fps` × the number of animated canvases. |
+| Constrained bandwidth | `{ enabled: true, imageQuality: 0.3 }` plus `replay.blockedSelectors` | Lower quality shrinks each image; blocked canvases are skipped entirely. |
+| CPU-sensitive pages (low-end devices) | `{ enabled: true, imageType: "image/png" }` | PNG encodes much faster than webp but produces about twice the bytes. |
+
+For scale, on a test dashboard with six canvas charts on a 2× display, canvas capture added about
+280 KB/min while the charts were static and about 1 MB/min while they refreshed every 10 s. The
+recorder used about 12% of a CPU core at 1 fps and about 35% at 4 fps, with the same bytes. PNG at
+4 fps used about 10%.
+
+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 +389,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,45 @@ 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 1 and is clamped to
+     * [1, 15]; out-of-range values are clamped with a `console.warn`. Maps to
+     * rrweb's `sampling.canvas`. Every canvas is re-encoded on every tick, so a
+     * higher rate costs CPU even when nothing changes; it adds bytes only for
+     * canvases that change faster than the rate. Raise it for animated canvases.
+     */
+    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 +378,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 +414,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,45 @@ 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 1 and is clamped to
+     * [1, 15]; out-of-range values are clamped with a `console.warn`. Maps to
+     * rrweb's `sampling.canvas`. Every canvas is re-encoded on every tick, so a
+     * higher rate costs CPU even when nothing changes; it adds bytes only for
+     * canvases that change faster than the rate. Raise it for animated canvases.
+     */
+    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 +378,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 +414,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;
 }