[jxiwang]

Summary

Connect semantic context capture to Session Replay through a locally supplied implementation. Applications opt in with:

import { createSemanticCapture } from '@amplitude/amp-semantic';

sessionReplay.init(API_KEY, {
  semanticCapture: { enabled: true, createCapture: createSemanticCapture },
});

Session Replay has no production dependency or public declaration dependency on amp-semantic. It defines a small structural callback, host, and controller contract; the semantic package remains a development-only dependency for compatibility tests. Without a local createCapture callback, capture stays inactive even when remote configuration enables it. Remote config can change enabled, sampling, and family controls, but cannot replace the callback. The analytics plugin forwards the local callback unchanged.

The adapter waits for rrweb readiness, forwards accepted full snapshots, resets sampling and caps for a new session, and stops capture with recording. Replacing the callback stops its previous runtime; an initialization error does not abort replay setup. The replay host owns tab/document identity using its existing core UUID helper. A bounded startup queue does not import recorder-specific caps.

Context travels through existing rrweb type-5 custom events. Include the local-only playground and Chromium tests for actual transport, capture gates, and stop/resume. This increment enables only context; visibility follows in #2128.

Review fixes

• A session change stops only the prior semantic runtime during config refetch; rrweb remains recording until the normal restart.
• Semantic rrweb custom-event emission catches and logs recorder errors without interrupting replay.
• Invalid remote semantic sample rates warn and disable semantic capture; values in [0, 1] are retained.

Stack

Base: main (runtime #2120 and context #2126 are merged). Visibility (#2128) remains stacked on this branch.

Validation

Updated against main on November 9, 2026, including the published amp-semantic@0.3.0 package. The merge conflict is resolved; the resulting PR diff contains only integration work.

• Node 24: install, workspace build, docs, lint, dependency checks, typecheck, and all 32 workspace test projects passed.
• Seven Chromium transport tests passed, including missing createCapture with remote capture enabled.
• Session Replay retains 100% coverage (1,161 tests); compatibility tests type-check the real semantic callback against the public injection contract.
• Existing bundle limits pass. Context-only standalone replay is about 143 kB gzipped; source maps for standalone replay, its analytics plugin, and unified contain no amp-semantic modules. Emitted replay declarations and JS contain no imports from that package.
• Existing blocker retained with prior maintainer approval: pnpm test:examples cannot start because jest.setup.examples.js is absent on main.

---

Note

Medium Risk
Changes run on the replay recording path and attach privacy/configuration context to the stream, but capture is off by default, requires a local factory, and semantic failures are isolated from rrweb teardown.

Overview
Wires opt-in semantic context into Session Replay via a local createCapture callback (no production dependency on @amplitude/amp-semantic). Apps enable semanticCapture: { enabled: true, createCapture: createSemanticCapture }; without the factory, capture stays inert even when remote config turns it on.

Session Replay adds a structural host/adapter (ReplaySemanticAdapter) that waits for rrweb readiness, triggers capture on accepted full snapshots, emits amp-semantic/context as type-5 custom events, and tears down on stop/reinit/session changes without blocking normal recording. Tab/document identity is allocated lazily with sessionStorage when available. Remote sr_semantic_config can adjust enabled, sample rate, and families; the local createCapture callback is preserved and invalid remote sample rates warn and force 0.

The analytics Session Replay plugin forwards semanticCapture and reports active autocapture families as semanticAnalyticsContext. Documentation, a local vite harness (sr-semantic-test), and Playwright e2e plus unit/integration tests cover transport, gates, lifecycle, and joined-config behavior.

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

[github-actions]

Session Replay Browser E2E Results

 159 passed

Details

 159 tests across 18 suites
 4 minutes, 8 seconds
 e55359f

[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	140.38 KB (+0.87% 🔺)
packages/unified/lib/scripts/amplitude-min.umd.js.gz	226.78 KB (+0.66% 🔺)
@amplitude/element-selector (gzipped esm)	3.48 KB (0%)
@amplitude/analytics-browser/lite (gzipped CDN bundle)	21.29 KB (0%)

[jxiwang]

bugbot run

[cursor]

Stale Bugbot comment from a previous run.

[jxiwang]

bugbot run

[cursor]

Stale Bugbot comment from a previous run.

[linear-code]

SRAI-128

[jxiwang]

bugbot run

[cursor]

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

There are 5 total unresolved issues (including 4 from previous reviews).

^{❌ 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 2c4773f. Configure here.}