[jxiwang]

Summary

Wire opt-in semantic capture into session-replay-browser and its analytics plugin. Start capture only after rrweb is available, emit context around full snapshots, forward navigation and recording lifecycle signals, and preserve disabled behavior and sampling boundaries across replay sessions.

This is the original lifecycle/SDK workstream. Final visibility-only transitions, user agent context, and tab/document identity are refinements in the final integration slice.

Related: SRAI-56, SRAI-64, SRAI-65.

Review stack

This is a draft review slice of the amp-semantic work. Review in order: interactions → lifecycle → page-feedback → integration. The final codex/semantic-review-integration tree is identical to the tested codex/amp-semantic tree after removing temporary capture diagnostics. Existing implementation workstream branches are preserved.

Do not merge these slices independently yet. The final integration PR supplies the runtime entry point, shared helpers, complete schema, lockfile registration, and later refinements. Intermediate slices are not independently buildable/releasable. Before promoting the stack, arrange independently green boundaries or land the complete stack together.

Validation on the complete integration tree

Node 24.22.1 / pnpm 11.28.5:

• Passed frozen-lockfile install, pnpm docs:check, pnpm lint (30 projects), and pnpm lint:deps.
• Passed @amplitude/amp-semantic ES5/ESM build and replay SDK/plugin ES5/ESM builds.
• Passed 148 semantic unit tests, 18 replay adapter/identity tests, and all 22 Chromium integration tests. Focused unit commands used --coverage=false; this does not satisfy the coverage gate.
• pnpm test fails the new semantic package's inherited 100% coverage thresholds (statements 90.8%, branches 81.65%, functions 85.86%, lines 94.18%). All 148 semantic assertions pass; dependent tasks were not all run after that failure.
• pnpm test:examples fails because the configured jest.setup.examples.js is absent from this checkout.
• pnpm build emitted the replay plugin bundles but did not exit; its idle Rollup process was stopped after more than ten minutes. Full repository build is not verified.

These are draft blockers, not green CI. Node 22/26 and current-main integration still need CI validation. Results above apply to the complete stack, not each intermediate branch.

Checklist

• Conventional commit PR title.
• Breaking change: No intended public API break; semantic capture is opt-in.
• Resolve validation blockers before marking ready.

[jxiwang]

Superseded for merging by the clean stack: context #2126 and SDK integration #2127 (merged), visibility #2128, lifecycle #2150, navigation #2151, and recording boundaries #2152. The old branch remains available as a reference.