@groundcover/browser 0.1.0 → 1.0.0

package/README.md

@@ -1,222 +1,242 @@
-# groundcover RUM Browser Monitoring
+<p align="center">
+  <img src="./assets/logo.png" alt="groundcover" width="240" />
+</p>
 
-groundcover’s Real User Monitoring (RUM) SDK allows you to capture front-end performance data, user events, and errors from your web applications.
+<h1 align="center">RUM — Browser SDK</h1>
 
-See the dedicated [groundcover documentation](https://docs.groundcover.com/capabilities/real-user-monitoring-rum/) for more details.
+<p align="center">
+  <a href="https://www.npmjs.com/package/@groundcover/browser"><img src="https://img.shields.io/npm/v/@groundcover/browser.svg" alt="npm version" /></a>
+  <a href="https://bundlejs.com/?q=@groundcover/browser"><img src="https://img.shields.io/bundlejs/size/@groundcover/browser" alt="minzipped size" /></a>
+  <a href="https://github.com/groundcover-com/rum/actions/workflows/ci.yml"><img src="https://github.com/groundcover-com/rum/actions/workflows/ci.yml/badge.svg" alt="CI status" /></a>
+</p>
 
-## Installation
+groundcover’s Real User Monitoring (RUM) SDK captures front-end **performance**, **user
+interactions**, **errors**, **logs**, **distributed traces**, and **session replay** from your web
+application — with privacy masking **on by default**.
 
-```bash
-npm install @groundcover/browser
-```
+> Session replay is powered by [**rrweb**](https://github.com/rrweb-io/rrweb) under the hood.
 
-## Initialize the SDK
+See the [groundcover RUM documentation](https://docs.groundcover.com/capabilities/real-user-monitoring-rum/)
+for the full product guide.
 
-```ts
-import groundcover from "@groundcover/browser";
+---
 
-groundcover.init({
-  apiKey: "your-api-key",
-  cluster: "your-cluster",
-  environment: "production",
-  dsn: "your-dsn",
-  appId: "your-app-id",
-});
-```
+## Table of contents
 
-### Micro-frontend Session Synchronization
+- [Quick start](#quick-start)
+- [Configuration reference](#configuration-reference)
+- [Privacy & data masking](#privacy--data-masking)
+- [Session replay](#session-replay)
+- [Architecture](#architecture)
+- [Web Worker offloading](#web-worker-offloading)
+- [Session lifecycle](#session-lifecycle)
+- [Performance considerations](#performance-considerations)
+- [API reference](#api-reference)
+- [Migrating to 1.0.0](#migrating-to-100)
 
-For micro-frontend architectures, you can synchronize sessions across different frontend applications by passing a shared sessionId:
+---
+
+## Quick start
+
+```bash
+npm install @groundcover/browser
+```
 
 ```ts
-// Main application generates a sessionId
-const sharedSessionId = "session-12345";
+import groundcover from "@groundcover/browser";
 
-// Initialize SDK in main app
 groundcover.init({
   apiKey: "your-api-key",
-  cluster: "your-cluster",
-  environment: "production",
   dsn: "your-dsn",
-  appId: "your-app-id",
-  sessionId: sharedSessionId, // Use shared sessionId
-});
-
-// Initialize SDK in micro-frontend with same sessionId
-groundcover.init({
-  apiKey: "your-api-key",
   cluster: "your-cluster",
+  appId: "your-app-id",
   environment: "production",
-  dsn: "your-dsn",
-  appId: "micro-frontend-app-id",
-  sessionId: sharedSessionId, // Same sessionId for session continuity
 });
 ```
 
-## Identify users
-
-Link RUM data to specific users:
+That single call installs every instrumentation (page loads, DOM interactions, network requests,
+errors, console logs, navigation, performance, and session replay) and starts sending data. From
+here you can enrich it:
 
 ```ts
-groundcover.identifyUser({
-  id: "John Doe",
-  email: "john@groundcover.com",
-  organization: "groundcover",
-});
-```
+// Tie events to a user
+groundcover.identifyUser({ id: "u_123", email: "john@acme.com", organization: "acme" });
 
-## Send custom events
+// Capture a handled error
+groundcover.captureException(new Error("Checkout failed"), { feature: "checkout" });
 
-Send custom events to groundcover:
+// Emit a structured log
+groundcover.logger.warn("Payment retry", { provider: "stripe", attempt: 2 });
 
-```ts
-groundcover.track("custom-event");
+// Emit a custom business event
+groundcover.sendCustomEvent({ event: "plan_upgraded", attributes: { plan: "pro" } });
 ```
 
-## Capture structured logs
+---
 
-Use the `logger` API to send log messages with structured attributes that become queryable fields on the backend. The API mirrors Sentry's [`Sentry.logger`](https://docs.sentry.io/platforms/javascript/logs/) pattern — one method per level, second arg is the attributes object:
+## Configuration reference
+
+`init()` takes connection/identity fields at the top level and all behavioral knobs under
+`options`, grouped by concern.
 
 ```ts
-groundcover.logger.warn("Checkout failed", {
-  orderId: "ord_42",
-  region: "us-east",
-  cart: { items: 3, total: 99.99 },
-});
+groundcover.init({
+  // ── Connection & identity ──
+  apiKey, dsn, cluster, appId,
+  environment, namespace, releaseId,
+  user, sessionId,
 
-groundcover.logger.info("User signed in", { userId: "u_123" });
-groundcover.logger.error("Payment gateway timeout", { provider: "stripe" });
+  options: {
+    debug,
+    sessionSampleRate, eventSampleRate,
+    enabledEvents, excludedUrls,
+    sessionMaxDuration,
+    beforeSend, enrichEvent,
+    privacy:   { /* … */ },
+    tracing:   { /* … */ },
+    transport: { /* … */ },
+    replay:    { /* … */ },
+  },
+});
 ```
 
-Available levels: `log`, `info`, `warn`, `error`, `debug`, `trace`. Nested attribute objects are automatically flattened to dotted keys (e.g. `cart.items`, `cart.total`).
+### Top-level (connection & identity)
 
-### Structured `console.*` capture
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `apiKey` | `string` | ✅ | Your groundcover RUM API key. |
+| `dsn` | `string` | ✅ | RUM intake endpoint. A bare host is upgraded to `https://`. |
+| `cluster` | `string` | ✅ | Target groundcover cluster. |
+| `appId` | `string` | ✅ | Application identifier; reported as `service.name`. |
+| `environment` | `string` | — | Deployment environment (e.g. `production`, `staging`). |
+| `namespace` | `string` | — | Logical grouping/namespace for the app. |
+| `releaseId` | `string` | — | Release/version identifier (e.g. a semver or commit hash). |
+| `user` | `Partial<UserIdentifiers>` | — | Identify the user at init (same shape as [`identifyUser`](#identifyuser)). |
+| `sessionId` | `string` | — | Use a shared session id — see [micro-frontends](#micro-frontend-session-synchronization). |
+| `options` | `Partial<SDKOptions>` | — | Behavioral configuration, below. |
+
+### `options` — top-level knobs
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `debug` | `boolean` | `false` | Verbose SDK console logging. |
+| `sessionSampleRate` | `number` | `1` | Fraction of sessions captured (0–1). |
+| `eventSampleRate` | `number` | `1` | Fraction of events captured (0–1). |
+| `enabledEvents` | `Array<…>` | `[]` | Instrumentations to enable. **Empty = all.** Members: `dom`, `network`, `exceptions`, `logs`, `pageload`, `navigation`, `performance`, `replay`. |
+| `excludedUrls` | `Array<string \| RegExp>` | — | Network requests matching these are not captured. |
+| `sessionMaxDuration` | `number` | `4h` | Target max session length in ms (1 min – 8 h). See [session lifecycle](#session-lifecycle). |
+| `beforeSend` | `(event) => boolean` | — | Drop gate — return `false` to discard an event. Runs after redaction/enrichment; see [event lifecycle](#architecture). |
+| `enrichEvent` | `(event) => event` | — | Mutate/replace an event before batching. Runs right after `beforeSend`; see [event lifecycle](#architecture). |
 
-The SDK auto-captures `console.log` / `info` / `warn` / `error` / `debug` / `trace` calls. When any argument is a plain object, its keys are promoted to structured log attributes alongside the stringified message — no code changes required:
+### `options.privacy`
 
-```ts
-console.log("User action emitted", {
-  appId: "web",
-  environment: "prod",
-  userAction: { type: "click", target: "checkout-button" },
-});
-// → log event attributes include: appId, environment, userAction.type, userAction.target
-```
+Drives both replay and non-replay masking. **On by default.** See
+[Privacy & data masking](#privacy--data-masking) for the full table.
 
-Reserved keys (`message`, `level`, `location`) cannot be overridden by user-supplied attributes — `message` and `level` are stamped by the SDK, and `location` is always set from the current browser URL/path/title.
+### `options.tracing`
 
-## Capture errors
+Distributed-tracing header propagation for outgoing requests.
 
-Capture errors from your web application:
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `propagationUrls` | `string[]` | `[]` | Request URLs (prefix/`*`-glob match) that receive injected tracing headers. |
+| `propagationHeaders` | `string[]` | `[]` | Header names to read/propagate onto traced requests. |
+| `traceIdHeaderName` | `string` | `""` | Header carrying the trace id. |
+| `spanIdHeaderName` | `string` | `""` | Header carrying the span id. |
+| `origin` | `{ name: string; value: string }` | `{ name: "", value: "" }` | Origin tag stamped on injected trace headers. |
 
 ```ts
-groundcover.captureException(new Error("Something went wrong"));
+options: {
+  tracing: {
+    propagationUrls: ["https://api.acme.com/*"],
+    traceIdHeaderName: "x-groundcover-trace-id",
+    spanIdHeaderName: "x-groundcover-span-id",
+  },
+}
 ```
 
-You can also attach metadata to provide additional context:
+### `options.transport`
 
-```ts
-groundcover.captureException(new Error("Payment failed"), {
-  userId: "123",
-  feature: "checkout",
-  cart: { items: 3, total: 99.99 },
-});
-```
-
-## Optional Configuration
-
-You can customize SDK behavior (event sampling, data masking, enabled events). The following properties are customizable:
-
-```typescript
-export interface SDKOptions {
-  batchSize: number;
-  batchTimeout: number;
-  eventSampleRate: number;
-  sessionSampleRate: number;
-  environment: string;
-  debug: boolean;
-  tracePropagationUrls: string[];
-  sessionMaxDuration?: number; // optional; default 4h, range 1 minute – 8 hours (ms)
-  privacy?: PrivacyOptions;    // data masking; ON by default — see "Privacy & data masking"
-}
-```
+Batching and delivery of outgoing events.
 
-`sessionMaxDuration` sets a **target** maximum wall-clock session length (default 4 hours, must be between 1 minute and 8 hours).
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `batchSize` | `number` | `10` | Max events buffered before a batch flushes. |
+| `batchTimeout` | `number` | `10000` | Max ms a batch waits before flushing regardless of size. |
+| `compression` | `boolean` | `true` | Gzip-compress batches (offloaded to the Web Worker when available). |
 
-It is enforced **lazily, on activity — not by a background timer**, so it is **not a hard upper bound**. Once the cap has elapsed, the *next* user/business event (click, navigation, log, custom, network, exception, …) flushes pending events under the current session id, generates a fresh id, and resumes replay recording if it had been active.
+### `options.replay`
 
-Because rotation is activity-gated, a session that goes idle keeps its id past the cap until the next qualifying event:
+Session-replay recording controls. **This is noise reduction, not privacy** — to mask sensitive
+content use [`privacy`](#privacy--data-masking).
 
-- A dormant or backgrounded tab that produces no further events stays on the same session id — by design, so the SDK doesn't mint "phantom" sessions for tabs nobody is using.
-- **Session-replay batches don't count as activity** (rrweb emits a snapshot heartbeat every ~30s regardless of interaction), so a tab that's only recording replay won't rotate on that alone. Such a tab is ultimately bounded by the 30-minute replay-inactivity stop, not by this cap.
+| 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). |
 
-The flush is best-effort and the rotation always proceeds regardless of delivery success. Values outside the allowed range or otherwise invalid fall back to the default with a `console.warn`.
+> ⚠️ 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.
 
-## Privacy & data masking
+### Updating config at runtime
 
-**Masking is ON by default.** With no `privacy` config the SDK runs at
-`privacy.level: 'mask-sensitive'`, which drives masking for both session replay
-and non-replay events (DOM / network / logs / errors).
+`updateConfig` mirrors the `init` shape; 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:
 
-```typescript
-groundcover.init({
-  /* … */
+```ts
+groundcover.updateConfig({
   options: {
-    privacy: {
-      level: "mask-sensitive", // 'mask-sensitive' (default) | 'mask-all' | 'allow'
-      maskSelectors: [".cc-number", "[data-secret]"], // always masked (replay + DOM)
-      sensitiveKeys: ["account_number"],              // extra case-insensitive key substrings
-      // maskNetworkBodies / maskNetworkQueryParams / maskLogs / maskErrors: default true
-    },
+    transport: { batchSize: 20 }, // batchTimeout/compression are preserved
+    privacy: { level: "mask-all" },
   },
 });
 ```
 
-### Levels
-
-| Level | Inputs / keystrokes | Static page text | Network bodies, query params, logs, errors |
-|---|---|---|---|
-| `mask-sensitive` *(default)* | only **sensitive** form controls masked; all others captured | captured (except `data-private` / `maskSelectors` subtrees) | redacted by sensitive-key matching |
-| `mask-all` | **all** inputs masked | masked | redacted |
-| `allow` | captured | captured | not redacted |
+For `user`, an omitted key leaves the current identity untouched, passing an object merges into it,
+and passing `null` clears it (e.g. on logout).
 
-Under the default `mask-sensitive`, there are **two kinds of signal**.
+---
 
-**Explicit / container signals** — mask the element *and its whole subtree*,
-whether it holds a form input or static text:
-
-- it **or any ancestor** has a `data-private` attribute;
-- it **or any ancestor** matches one of `privacy.maskSelectors`;
-- one of its `id` / `name` / `class` / `aria-label` / `placeholder` attributes
-  contains a legacy `maskFields` substring.
+## Privacy & data masking
 
-**Built-in field heuristic** — applies **only to form controls**
-(`<input>`, `<textarea>`, `<select>`), so ordinary static page text stays
-visible:
+Masking is **on by default** (`privacy.level: 'mask-sensitive'`). A single `level` is the master
+switch; finer toggles and hooks refine it.
 
-- it is `<input type="password">`;
-- one of its `id` / `name` / `class` / `aria-label` / `placeholder` attributes
-  matches a built-in sensitive-key pattern (`password`, `secret`, `token`,
-  `api-key`, `access-key`, `auth`/`authorization`, `bearer`, `credential`,
-  `cvv`, `ssn`, `card-number`, …) or one of your `privacy.sensitiveKeys`.
+| `level` | Replay inputs | Replay text | DOM events | Network / logs / errors |
+|---|---|---|---|---|
+| `mask-sensitive` **(default)** | sensitive masked | `[data-private]` + `maskSelectors` masked | sensitive masked | redacted |
+| `mask-all` | masked | masked (`*`) | all masked | redacted |
+| `allow` | — | — | — | off (auth headers are still stripped) |
 
-So a non-secret form control (search, name, description, date, numeric field) is
-captured with its real value, and a **static** element is never masked by the
-field heuristic alone — e.g. `<div id="token">` stays visible. To mask a
-sensitive **static** value, mark it with `data-private` or a `maskSelectors`
-entry (both also apply in session replay). Use `'mask-all'` to mask every input
-plus all static text, or `'allow'` to disable masking entirely.
+Under `mask-sensitive`, an input/element is masked when it is a `type="password"`, sits under a
+`[data-private]` ancestor or a `maskSelectors` match, or has an `id`/`name`/`class`/`aria-label`/
+`placeholder` matching a built-in sensitive-key pattern or your `sensitiveKeys`. Non-sensitive inputs
+and static page text stay visible; use `[data-private]` / `maskSelectors` to mask static content.
 
-For **session replay**, non-input/static text (e.g. a value in a
-`contenteditable` or a plain `<div>`) is masked when it sits under a
-`data-private` or `privacy.maskSelectors` subtree; the built-in field heuristic
-does not mask arbitrary text.
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `level` | `'mask-sensitive' \| 'mask-all' \| 'allow'` | `'mask-sensitive'` | Master masking switch. |
+| `maskSelectors` | `string[]` | — | CSS selectors whose text/inputs are always masked (replay + DOM), unless `level: 'allow'`. |
+| `maskNetworkBodies` | `boolean` | `true` | Redact network request/response bodies. |
+| `maskNetworkQueryParams` | `boolean` | `true` | Redact URL query params. |
+| `maskLogs` | `boolean` | `true` | Redact console/log messages and attributes. |
+| `maskErrors` | `boolean` | `true` | Redact error messages, metadata and stack-frame URLs. |
+| `sensitiveKeys` | `string[]` | — | Extra case-insensitive key substrings treated as sensitive, merged with built-ins. |
+| `redact` | `(field) => value \| undefined` | — | Per-leaf custom redactor for non-replay events. Return `undefined` to defer to the SDK default. |
+| `replay.maskTextFn` | `(text, el) => string` | — | rrweb `maskTextFn` pass-through (replay only). |
+| `replay.maskInputFn` | `(text, el) => string` | — | rrweb `maskInputFn` pass-through (replay only). |
 
-Regardless of level (even `allow`), built-in sensitive request/response **headers**
-(`authorization`, `cookie`, `set-cookie`, and `token`/`key`/`secret`/`password`-like
-names) are always stripped.
+```ts
+options: {
+  privacy: {
+    level: "mask-sensitive",
+    maskSelectors: [".pii", "#ssn"],
+    sensitiveKeys: ["account_no"],
+  },
+}
+```
 
-### Built-in sensitive patterns
+#### Built-in sensitive patterns
 
 These are always treated as sensitive (case-insensitive); your `sensitiveKeys` are merged in on top.
 
@@ -231,58 +251,216 @@ These are always treated as sensitive (case-insensitive); your `sensitiveKeys` a
 - **Query / form param names** — matched as a whole key (not inside JSON bodies), for OAuth-style
   callbacks: `code`, `state`, `session_state`, `id_token`, `access_token`, `refresh_token`, `token`.
 
-To opt out of body/DOM masking: `privacy: { level: "allow" }`. Built-in sensitive
-headers (`authorization`/`cookie`/`set-cookie` and `token`/`key`/`secret`/`auth`-like
-names) are still stripped regardless of level.
+To opt out entirely: `privacy: { level: "allow" }`.
+
+---
+
+## Session replay
+
+Replay is recorded with [**rrweb**](https://github.com/rrweb-io/rrweb). The SDK wires rrweb’s
+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)
+
+Recording starts automatically when `replay` is enabled (it is, by default — empty `enabledEvents`).
+You can also control it manually:
+
+```ts
+groundcover.startReplayRecording();
+groundcover.stopReplayRecording();
+```
+
+> rrweb mask options are fixed at `record()` time. Changing privacy config at runtime via
+> `updateConfig` automatically **restarts** the active recording so the new masking applies.
+
+---
+
+## Architecture
+
+Every captured event flows through one pipeline from instrumentation to intake. The two public
+hooks — **`beforeSend`** (drop gate) and **`enrichEvent`** (transform) — run in the events pool,
+*after* privacy redaction and internal enrichment, so they always see the final, already-redacted
+event.
+
+```mermaid
+flowchart TD
+    L["Listeners (events/listeners)<br/>dom · network · errors · logs<br/>navigation · pageload · performance · replay"]
+    R["Privacy redaction<br/>(getPrivacy) — bodies, headers,<br/>query params, logs, errors"]
+    EI["Internal enrichment<br/>id · span/trace ids · timestamps · location"]
+    BS{"beforeSend(event)<br/>returns false?"}
+    DROP["✗ dropped"]
+    EN["enrichEvent(event)<br/>mutate / replace"]
+    P["events-pool<br/>batch by transport.batchSize / transport.batchTimeout"]
+    T["transporter<br/>gzip (transport.compression)"]
+    I[("groundcover intake")]
+
+    L --> R --> EI --> BS
+    BS -- "false" --> DROP
+    BS -- "keep" --> EN --> P --> T --> I
+```
 
-### Advanced
+**Event lifecycle (in order):**
 
-- `privacy.redact(field)` — per-leaf hook for full control over non-replay
-  redaction (network/log/error). Return a replacement primitive, or `undefined`
-  to defer to the SDK default.
-- `privacy.replay.maskTextFn` / `privacy.replay.maskInputFn` — rrweb
-  pass-throughs for session-replay text/input masking. A custom `maskInputFn`
-  takes over input masking in the replay (it is called for every input).
+1. **Capture** — a listener builds the raw event.
+2. **Redact** — sensitive payload is masked per the resolved [`privacy`](#privacy--data-masking) config.
+3. **Enrich (internal)** — the SDK stamps id / span & trace ids / timestamps / `location` (location query params are redacted here too).
+4. **`beforeSend(event)`** — your hook; return `false` to **drop** the event. Receives the fully-redacted, enriched event.
+5. **`enrichEvent(event)`** — your hook; mutate or replace the event before it’s buffered.
+6. **Batch** — buffered in the events pool, flushed at `transport.batchSize` or `transport.batchTimeout`.
+7. **Send** — gzipped (`transport.compression`) and delivered to intake.
 
-> The legacy `enableMasking` / `maskFields` options are **deprecated** but still
-> honored: `enableMasking: true` → `'mask-all'`, explicit `enableMasking: false`
-> → `'allow'`, and `maskFields` entries match DOM element attributes. Prefer
-> `privacy.level` / `privacy.maskSelectors` / `privacy.sensitiveKeys`.
+Supporting pieces:
 
-Attributes you send **explicitly** via `groundcover.sendCustomEvent(...)` are
-**not** auto-redacted — scrub them before sending (or via `enrichEvent`).
+- **`instrumentation-manager`** installs listeners per `enabledEvents`.
+- **`config-manager`** holds the resolved `SDKConfig` and a memoized `getPrivacy()` read by every
+  listener; runtime `updateConfig` invalidates the privacy memo.
+- **`session-manager`** owns the session lifecycle — see [below](#session-lifecycle).
+- **`worker`** offloads replay packing + gzip off the main thread.
+
+> Note: `beforeSend`/`enrichEvent` do **not** see explicitly-sent `sendCustomEvent` payloads pre-redacted —
+> those are deliberately-provided and are not auto-redacted; scrub them yourself or via `enrichEvent`.
+
+---
 
 ## Web Worker offloading
 
-The SDK spawns a dedicated Web Worker on init and offloads CPU-heavy work — session-replay event packing and outgoing-batch gzip — off the main thread so it doesn't compete with the host page's UI work.
+The SDK spawns a dedicated Web Worker on init and offloads CPU-heavy work — session-replay event
+packing and outgoing-batch gzip — off the main thread so it doesn’t compete with your page’s UI
+work.
 
-The worker is bundled inline (no extra files to host) and spawned from a `blob:` URL. On environments that don't permit blob-sourced workers — strict Content Security Policy without `worker-src 'self' blob:`, sandboxed iframes, SSR — the SDK silently falls back to the existing main-thread implementation. Behavior, wire format, and the public API are identical in both modes.
+The worker is bundled inline (no extra files to host) and spawned from a `blob:` URL. On
+environments that don’t permit blob-sourced workers — strict Content Security Policy without
+`worker-src 'self' blob:`, sandboxed iframes, SSR — the SDK silently falls back to the main-thread
+implementation. Behavior, wire format, and the public API are identical in both modes.
 
-You can pass the values by calling the init function:
+---
 
-```typescript
-groundcover.init({
-  apiKey: "your-api-key",
-  cluster: "your-cluster",
-  environment: "production",
-  dsn: "your-dsn",
-  appId: "your-app-id",
-  sessionId: "optional-session-id", // For micro-frontend synchronization
-  options: {
-    batchSize: 50,
-    sessionSampleRate: 0.5, // 50% sessions sampled
-    eventSampleRate: 0.5,
-  },
+## Session lifecycle
+
+`sessionMaxDuration` sets a **target** maximum wall-clock session length (default 4 hours; must be
+between 1 minute and 8 hours).
+
+It is enforced **lazily, on activity — not by a background timer**, so it is **not a hard upper
+bound**. Once the cap has elapsed, the *next* user/business event (click, navigation, log, custom,
+network, exception, …) flushes pending events under the current session id, mints a fresh id, and
+resumes replay recording if it had been active.
+
+Because rotation is activity-gated, a session that goes idle keeps its id past the cap until the
+next qualifying event:
+
+- A dormant or backgrounded tab that produces no further events stays on the same session id — by
+  design, so the SDK doesn’t mint “phantom” sessions for tabs nobody is using.
+- **Session-replay batches don’t count as activity** (rrweb emits a snapshot heartbeat every ~30s
+  regardless of interaction), so a tab that’s only recording replay won’t rotate on that alone. It’s
+  ultimately bounded by the 30-minute replay-inactivity stop, not by this cap.
+
+Sessions are also bounded by a 30-minute inactivity gap, enforced the same lazy way. The flush is
+best-effort and the rotation always proceeds regardless of delivery success. Invalid values fall
+back to the default with a `console.warn`.
+
+### Micro-frontend session synchronization
+
+Pass a shared `sessionId` so multiple frontends report under one session:
+
+```ts
+const sharedSessionId = "session-12345";
+groundcover.init({ /* …app… */ apiKey, dsn, cluster, appId: "shell", sessionId: sharedSessionId });
+groundcover.init({ /* …mfe… */ apiKey, dsn, cluster, appId: "micro-frontend", sessionId: sharedSessionId });
+```
+
+---
+
+## Performance considerations
+
+- **Batching & compression** — events are buffered (`transport.batchSize` / `transport.batchTimeout`) and
+  gzipped (`transport.compression`) to minimize request count and payload size.
+- **Web Worker offload** — replay packing and gzip run off the main thread (see above).
+- **Sampling** — cap volume with `sessionSampleRate` / `eventSampleRate`.
+- **Scope what you capture** — drop noisy endpoints with `excludedUrls`, and disable unused
+  instrumentations via `enabledEvents`.
+- **Lazy session rotation** — no background timers; rotation work happens only on real activity.
+- **Bundle size** — ships ESM + CJS with built-in types; the published bundle is size-budgeted in
+  CI.
+
+---
+
+## API reference
+
+All methods are available on the default export and on `window.groundcover`.
+
+| Method | Description |
+|---|---|
+| `init(config)` | Initialize the SDK and install instrumentation. |
+| `identifyUser(user)` | Attach user identity to subsequent events. |
+| `sendCustomEvent({ event, attributes })` | Emit a custom business event. |
+| `captureException(error, metadata?)` | Capture a handled error with optional context. |
+| `logger.{log,info,warn,error,debug,trace}(message, attributes?)` | Structured logging (see below). |
+| `updateConfig({ options?, user?, … })` | Update config at runtime (merges nested groups one level deep). |
+| `startNavigation(metadata)` / `endNavigation(metadata)` | Manual navigation spans (when `navigation` isn’t auto-tracked). |
+| `getSessionId()` / `setSessionId(id?)` | Read / override the current session id. |
+| `startReplayRecording()` / `stopReplayRecording()` | Manually control session replay. |
+
+### Structured logs
+
+`groundcover.logger` mirrors Sentry’s `logger` pattern — one method per level, second arg is the
+attributes object. Nested objects are flattened to dotted keys:
+
+```ts
+groundcover.logger.warn("Checkout failed", {
+  orderId: "ord_42",
+  cart: { items: 3, total: 99.99 }, // → cart.items, cart.total
 });
 ```
 
-Or via the updateConfig function (options are nested under `options`,
-matching the `init` shape):
+The SDK also auto-captures `console.*` calls; when any argument is a plain object, its keys are
+promoted to structured log attributes. Reserved keys (`message`, `level`, `location`) are always
+set by the SDK and can’t be overridden.
 
-```typescript
-groundcover.updateConfig({
-  options: {
-    batchSize: 20,
-  },
+### `identifyUser`
+
+```ts
+groundcover.identifyUser({
+  id: "u_123",
+  email: "john@acme.com",
+  organization: "acme",
+});
+```
+
+### `captureException`
+
+```ts
+groundcover.captureException(new Error("Payment failed"), {
+  userId: "123",
+  feature: "checkout",
 });
 ```
+
+---
+
+## Migrating to 1.0.0
+
+`1.0.0` restructures `options` by concern (a clean break from `0.x`) and removes the deprecated
+masking flags. Update your config as follows:
+
+| `0.x` | `1.0.0` |
+|---|---|
+| `environment` *(duplicated in `options`)* | top-level `environment` only |
+| `userIdentifier` | `user` |
+| `options.sessionReplay.blockedSelectors` | `options.replay.blockedSelectors` |
+| `options.tracePropagationUrls` | `options.tracing.propagationUrls` |
+| `options.tracePropagationHeaders` | `options.tracing.propagationHeaders` |
+| `options.tracePropagationTraceIdHeaderName` | `options.tracing.traceIdHeaderName` |
+| `options.tracePropagationSpanIdHeaderName` | `options.tracing.spanIdHeaderName` |
+| `options.traceOrigin` | `options.tracing.origin` |
+| `options.batchSize` / `options.batchTimeout` | `options.transport.batchSize` / `options.transport.batchTimeout` |
+| `options.enableCompression` | `options.transport.compression` |
+| `options.enableMasking: true` *(removed — ignored)* | set `options.privacy.level: 'mask-all'` |
+| `options.enableMasking: false` *(removed — ignored)* | set `options.privacy.level: 'allow'` |
+| `options.maskFields` *(removed — ignored)* | set `options.privacy.maskSelectors` / `options.privacy.sensitiveKeys` |
+
+> ⚠️ The removed masking flags are **ignored, not auto-mapped** — passing `enableMasking` /
+> `maskFields` logs a `console.warn` and has **no effect**. You must set the corresponding `privacy`
+> option yourself (right-hand column). Masking remains **on by default** (`mask-sensitive`); if you
+> previously relied on masking being off, set `privacy: { level: 'allow' }` explicitly.