[jxiwang]

Summary

Add amp-semantic/context on top of the capture runtime in #2120. The recorder emits after a host-provided accepted full-snapshot signal, and reads SDK/privacy configuration, the effective mask level for the snapshot URL (including URL overrides), stylesheet counts, viewport, device heuristic, language, user agent, visibility/focus snapshots, analytics configuration, and dropped-event diagnostics.

This PR includes the context payload, wire schema, recorder tests, and documentation. It does not add Session Replay configuration, transport, or visibility listeners. The host must supply privacy settings and snapshot notifications. Context skips payload reads after its event budget and acknowledges dropped counts only after successful delivery. The shared runtime releases cap slots after failed transport, deduplicates cleanup callbacks, and preserves the reentrant setup fix merged in #2120.

Stack

Base: main after #2120 merged. Session Replay wiring follows in #2127, then visibility in #2128.

Validation

Node 24: install, full workspace build, package typecheck, docs, lint, dependency checks, and workspace tests passed. The semantic package has 39 passing tests with 100% coverage in all four metrics. A regression test covers matching URL mask overrides and fallback to the default level.

Existing blocker retained with prior maintainer approval: pnpm test:examples cannot start because jest.setup.examples.js is absent on main.

---

Note

Medium Risk
Expands what the runtime reads from the page (stylesheets, UA, privacy-derived mask) and breaks host typings by requiring new fields; privacy-adjacent but no transport/auth changes.

Overview
createSemanticCapture now wires the context family by default via defaultRecorders and fixed per-family caps (SEMANTIC_CAPS), so snapshot notifications produce amp-semantic/context unless callers pass a different recorder list. Low-level createCapture stays explicit for tests and extensions.

Hosts must supply sdk, getPrivacy, and optional getAnalyticsContext / inlineStylesheet. Types and fixtures reflect that. The new contextRecorder listens for snapshot, respects caps (canEmit), aggregates stylesheet stats (with cross-origin handling), effective mask from @amplitude/session-replay-dom-privacy, viewport, device heuristic, visibility/focus, UA, analytics SDK metadata, and optional caps_hit; it clears dropped diagnostics only after a successful emit.

Published artifacts include schema.json (rrweb custom-event shape for context), ajv-backed tests validate wired payloads, and README documents behavior and budgets. Lockfile and package.json add the privacy workspace dep and dev ajv.

^{Reviewed by Cursor Bugbot for commit 63198de. Bugbot is set up for automated code reviews on this repo. Configure here.}

[github-actions]

size-limit report 📦

Path	Size
packages/analytics-browser/lib/scripts/amplitude-min.js.gz	68.37 KB (0%)
packages/session-replay-browser/lib/scripts/session-replay-browser-min.js.gz	139.18 KB (0%)
packages/unified/lib/scripts/amplitude-min.umd.js.gz	225.31 KB (0%)
@amplitude/element-selector (gzipped esm)	3.48 KB (0%)
@amplitude/analytics-browser/lite (gzipped CDN bundle)	21.29 KB (0%)

[jxiwang]

bugbot run

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 0fbe740. Configure here.}