PANA-8500: Add foundation for pixel-based Session Replay capture

[jonathanmos]

What does this PR do?

Introduces the foundational models and pipeline selection for a new composition-tree-based Session Replay capture pipeline.

Unlike the existing pipeline, which uses semantic mappers for individual Android view types, the new pipeline captures the visual output of the application and represents it as an ordered composition tree.

This PR:

• Synchronizes the Session Replay wire schemas with composition-tree models.
• Defines internal contracts for captured layers, visual elements, pixel resources, and mutations.
• Generates stable, RUM-view-scoped identities for captured elements.
• Validates captured snapshots and mutations before serialization.
• Maps valid captured trees to Session Replay wire models.
• Adds the internal compositionTreeRecordingEnabled feature flag.
• Selects either the legacy semantic pipeline or the new composition-tree capture pipeline at initialization.

Pipeline selection is exclusive: only the selected recorder is constructed, and it handles the complete lifecycle of that recording cycle.

Motivation

The existing Session Replay pipeline reconstructs the UI using semantic, type-specific view mappers. This requires explicit knowledge of Android widget implementations and ongoing mapper support for different UI components.

The new pipeline is based on captured visual output rather than semantic reconstruction. This reduces its dependence on individual widget types and provides a common foundation for capturing content produced by different Android UI technologies.

Before the capture implementation can be connected, the pipeline needs:

• A stable representation of captured visual content and its layer structure.
• Deterministic identities across snapshots.
• Validation of tree structure, resources, and mutations.
• Conversion into the backend wire format.
• Flag-gated selection that leaves the existing recorder unchanged.

This PR provides those foundations. The composition-tree capture implementation and recording loop will be connected in subsequent work.

Additional Notes

• The new pipeline is disabled by default.
• The flag is internal and can be enabled through _SessionReplayInternalProxy.
• With the flag disabled, the existing SessionReplayRecorder is created and the composition-tree capture pipeline is not instantiated.
• The new recorder is currently a lifecycle shell.
• This PR does not make the new pipeline production-ready or change the public configuration API — SessionReplayConfiguration is untouched, and the flag is reachable only through _SessionReplayInternalProxy. The wire-model types (CompositionTree, CompositionLayer, and related modifier/gradient types) are new public classes, but purely additive and backward-compatible.

Review checklist (to be filled by reviewers)

• Feature or bugfix MUST have appropriate tests (unit, integration, e2e)
• Make sure you discussed the feature or bugfix with the maintaining team in an Issue
• Make sure each commit and the PR mention the Issue number (cf the CONTRIBUTING doc)

[codecov-commenter]

Codecov Report

❌ Patch coverage is 78.88889% with 171 lines in your changes missing coverage. Please review.
✅ Project coverage is 73.28%. Comparing base (47a97ee) to head (737d49a).

Files with missing lines	Patch %	Lines
...lay/internal/composition/CapturedTreeWireMapper.kt	57.14%	69 Missing and 18 partials ⚠️
...internal/composition/CapturedSnapshotValidation.kt	80.00%	8 Missing and 32 partials ⚠️
...internal/composition/CapturedMutationValidation.kt	80.00%	6 Missing and 13 partials ⚠️
...sessionreplay/internal/composition/CapturedTree.kt	90.00%	12 Missing ⚠️
...ionreplay/internal/composition/CapturedIdentity.kt	93.02%	3 Missing and 3 partials ⚠️
...internal/composition/CompositionCapturePipeline.kt	45.45%	6 Missing ⚠️
...play/internal/recorder/mapper/RadioButtonMapper.kt	0.00%	1 Missing ⚠️

Additional details and impacted files

@@                     Coverage Diff                     @@
##           feature/sr-new-pipeline    #3697      +/-   ##
===========================================================
+ Coverage                    73.11%   73.28%   +0.17%     
===========================================================
  Files                         1001     1009       +8     
  Lines                        36640    37432     +792     
  Branches                      6348     6516     +168     
===========================================================
+ Hits                         26787    27429     +642     
- Misses                        8029     8126      +97     
- Partials                      1824     1877      +53     

Files with missing lines	Coverage Δ
...com/datadog/android/sessionreplay/SessionReplay.kt	73.91% <100.00%> (+0.58%)	⬆️
...ndroid/sessionreplay/SessionReplayConfiguration.kt	97.00% <100.00%> (+0.57%)	⬆️
...droid/sessionreplay/_SessionReplayInternalProxy.kt	100.00% <100.00%> (ø)
.../sessionreplay/internal/DefaultRecorderProvider.kt	94.63% <100.00%> (+0.23%)	⬆️
...oid/sessionreplay/internal/SessionReplayFeature.kt	98.29% <100.00%> (+0.01%)	⬆️
...ionreplay/internal/composition/CapturedMutation.kt	100.00% <100.00%> (ø)
...play/internal/composition/CapturedTreeValidator.kt	100.00% <100.00%> (ø)
...replay/internal/processor/RecordedDataProcessor.kt	96.59% <100.00%> (ø)
...lay/internal/recorder/mapper/SwitchCompatMapper.kt	87.80% <100.00%> (ø)
...ssionreplay/recorder/mapper/BaseWireframeMapper.kt	100.00% <100.00%> (ø)
... and 7 more

... and 48 files with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[Copilot]

Pull request overview

Adds the initial internal “composition/layer-tree” (pixel-based) Session Replay foundations: new captured-tree models + validation + mapping to wire models, and a flag-gated recorder selection path that keeps the legacy semantic pipeline as default.

Changes:

• Introduces composition-tree capture contracts (identities, layers, wireframes, mutations), plus validation and mapping to MobileSegment wire models.
• Adds an internal layerTreeRecordingEnabled flag (exposed via _SessionReplayInternalProxy) and selects between legacy vs composition recorder at initialization.
• Extends wire schemas/models (composition tree, composition modifiers, embedded content wireframe, gradients, slotId) and updates tests/forgeries accordingly.

Reviewed changes

Copilot reviewed 70 out of 70 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
features/dd-sdk-android-session-replay/src/test/kotlin/com/datadog/android/sessionreplay/SessionReplayInternalProxyTest.kt	Adds unit test covering internal flag enabling via _SessionReplayInternalProxy.
features/dd-sdk-android-session-replay/src/test/kotlin/com/datadog/android/sessionreplay/SessionReplayConfigurationBuilderTest.kt	Verifies default value for layerTreeRecordingEnabled.
features/dd-sdk-android-session-replay/src/test/kotlin/com/datadog/android/sessionreplay/internal/utils/WireframeExtTest.kt	Updates tests for new EmbeddedContentWireframe handling in wireframe extensions.
features/dd-sdk-android-session-replay/src/test/kotlin/com/datadog/android/sessionreplay/internal/recorder/mapper/SwitchCompatMapperTest.kt	Aligns ShapeStyle construction with named opacity parameter.
features/dd-sdk-android-session-replay/src/test/kotlin/com/datadog/android/sessionreplay/internal/processor/WireframeUtilsTest.kt	Updates test helpers for new wireframe subtype handling.
features/dd-sdk-android-session-replay/src/test/kotlin/com/datadog/android/sessionreplay/internal/processor/NodeFlattenerTest.kt	Updates test helpers to support EmbeddedContentWireframe.
features/dd-sdk-android-session-replay/src/test/kotlin/com/datadog/android/sessionreplay/internal/processor/MutationResolverTest.kt	Updates test helpers to support EmbeddedContentWireframe.
features/dd-sdk-android-session-replay/src/test/kotlin/com/datadog/android/sessionreplay/internal/processor/BoundUtilsTest.kt	Updates test helpers to support EmbeddedContentWireframe.
features/dd-sdk-android-session-replay/src/test/kotlin/com/datadog/android/sessionreplay/internal/DefaultRecorderProviderTest.kt	Adds tests asserting exclusive pipeline construction based on flag.
features/dd-sdk-android-session-replay/src/test/kotlin/com/datadog/android/sessionreplay/internal/composition/CompositionTestTree.kt	Test fixture builder for minimal captured composition trees.
features/dd-sdk-android-session-replay/src/test/kotlin/com/datadog/android/sessionreplay/internal/composition/CompositionCapturePipelineTest.kt	Tests for feature-flag default and pipeline selection semantics.
features/dd-sdk-android-session-replay/src/test/kotlin/com/datadog/android/sessionreplay/internal/composition/CapturedTreeWireMapperTest.kt	Tests mapping captured snapshots/mutations into wire models + structured failures.
features/dd-sdk-android-session-replay/src/test/kotlin/com/datadog/android/sessionreplay/internal/composition/CapturedTreeValidatorTest.kt	Tests snapshot/mutation validation invariants and failure codes.
features/dd-sdk-android-session-replay/src/test/kotlin/com/datadog/android/sessionreplay/internal/composition/CapturedIdentityTest.kt	Tests deterministic, scoped, JS-safe identity generation.
features/dd-sdk-android-session-replay/src/test/kotlin/com/datadog/android/sessionreplay/internal/composition/CapturedContractsTest.kt	Tests ordering/clearing semantics for layers, modifiers, mutations, resources.
features/dd-sdk-android-session-replay/src/test/kotlin/com/datadog/android/sessionreplay/forge/WireframeForgeryFactory.kt	Extends random wireframe generation to include new subtypes.
features/dd-sdk-android-session-replay/src/test/kotlin/com/datadog/android/sessionreplay/forge/SessionReplayConfigurationForgeryFactory.kt	Adds layerTreeRecordingEnabled to config forgeries.
features/dd-sdk-android-session-replay/src/test/kotlin/com/datadog/android/sessionreplay/forge/ForgeConfigurator.kt	Registers new EmbeddedContentWireframe forgery factory.
features/dd-sdk-android-session-replay/src/test/kotlin/com/datadog/android/sessionreplay/forge/EmbeddedContentWireframeForgeryFactory.kt	New forgery factory for embedded-content wireframes.
features/dd-sdk-android-session-replay/src/main/kotlin/com/datadog/android/sessionreplay/SessionReplayConfiguration.kt	Adds internal layerTreeRecordingEnabled flag to configuration + internal builder setter.
features/dd-sdk-android-session-replay/src/main/kotlin/com/datadog/android/sessionreplay/SessionReplay.kt	Wires new config flag through feature initialization call.
features/dd-sdk-android-session-replay/src/main/kotlin/com/datadog/android/sessionreplay/recorder/mapper/BaseWireframeMapper.kt	Updates ShapeStyle construction to named opacity argument.
features/dd-sdk-android-session-replay/src/main/kotlin/com/datadog/android/sessionreplay/internal/utils/WireframeExt.kt	Adds EmbeddedContentWireframe branches for shapeStyle/copy/opaque checks.
features/dd-sdk-android-session-replay/src/main/kotlin/com/datadog/android/sessionreplay/internal/SessionReplayFeature.kt	Plumbs layerTreeRecordingEnabled into recorder provider construction.
features/dd-sdk-android-session-replay/src/main/kotlin/com/datadog/android/sessionreplay/internal/recorder/mapper/SwitchCompatMapper.kt	Updates ShapeStyle creation to named opacity.
features/dd-sdk-android-session-replay/src/main/kotlin/com/datadog/android/sessionreplay/internal/recorder/mapper/RadioButtonMapper.kt	Updates ShapeStyle creation to named opacity.
features/dd-sdk-android-session-replay/src/main/kotlin/com/datadog/android/sessionreplay/internal/processor/WireframeUtils.kt	Extends clip extraction to include EmbeddedContentWireframe.
features/dd-sdk-android-session-replay/src/main/kotlin/com/datadog/android/sessionreplay/internal/processor/RecordedDataProcessor.kt	Switches to named args for record constructors (timestamp/data).
features/dd-sdk-android-session-replay/src/main/kotlin/com/datadog/android/sessionreplay/internal/processor/MutationResolver.kt	Adds mutation resolution for EmbeddedContentWireframe updates.
features/dd-sdk-android-session-replay/src/main/kotlin/com/datadog/android/sessionreplay/internal/processor/MobileSegmentExt.kt	Adds EmbeddedContentWireframe branch to clip-copy extension.
features/dd-sdk-android-session-replay/src/main/kotlin/com/datadog/android/sessionreplay/internal/processor/HeatmapWireframeExt.kt	Adds EmbeddedContentWireframe support for permanentId copying/access.
features/dd-sdk-android-session-replay/src/main/kotlin/com/datadog/android/sessionreplay/internal/processor/BoundsUtils.kt	Adds EmbeddedContentWireframe bounds resolution.
features/dd-sdk-android-session-replay/src/main/kotlin/com/datadog/android/sessionreplay/internal/DefaultRecorderProvider.kt	Adds flag-gated pipeline selection and composition pipeline factory hook.
features/dd-sdk-android-session-replay/src/main/kotlin/com/datadog/android/sessionreplay/internal/composition/CompositionCapturePipeline.kt	Introduces feature flag constant, selector, and no-op composition recorder shell.
features/dd-sdk-android-session-replay/src/main/kotlin/com/datadog/android/sessionreplay/internal/composition/CapturedTreeWireMapper.kt	Implements captured snapshot/mutation → wire-model mapping with validation.
features/dd-sdk-android-session-replay/src/main/kotlin/com/datadog/android/sessionreplay/internal/composition/CapturedTreeValidator.kt	Defines validation result types and validator entry points.
features/dd-sdk-android-session-replay/src/main/kotlin/com/datadog/android/sessionreplay/internal/composition/CapturedTree.kt	Adds captured tree contracts (layers, wireframes, modifiers, resources).
features/dd-sdk-android-session-replay/src/main/kotlin/com/datadog/android/sessionreplay/internal/composition/CapturedSnapshotValidation.kt	Implements snapshot invariants validation (references, cycles, modifiers, resources).
features/dd-sdk-android-session-replay/src/main/kotlin/com/datadog/android/sessionreplay/internal/composition/CapturedMutationValidation.kt	Implements mutation validation (scope, duplicates, contradictions, targets).
features/dd-sdk-android-session-replay/src/main/kotlin/com/datadog/android/sessionreplay/internal/composition/CapturedMutation.kt	Defines mutation/change-set data structures.
features/dd-sdk-android-session-replay/src/main/kotlin/com/datadog/android/sessionreplay/internal/composition/CapturedIdentity.kt	Adds stable, deterministic identity generation scoped to a RUM view.
features/dd-sdk-android-session-replay/src/main/kotlin/com/datadog/android/sessionreplay/_SessionReplayInternalProxy.kt	Exposes internal flag toggling via _SessionReplayInternalProxy.
features/dd-sdk-android-session-replay/src/main/json/schemas/session-replay/mobile/wireframe-update-mutation-schema.json	Adds embedded-content update schema reference.
features/dd-sdk-android-session-replay/src/main/json/schemas/session-replay/mobile/wireframe-schema.json	Adds embedded-content wireframe schema reference.
features/dd-sdk-android-session-replay/src/main/json/schemas/session-replay/mobile/shape-style-schema.json	Adds backgroundGradient to shape style schema.
features/dd-sdk-android-session-replay/src/main/json/schemas/session-replay/mobile/shape-linear-gradient-schema.json	New schema defining linear gradients.
features/dd-sdk-android-session-replay/src/main/json/schemas/session-replay/mobile/shape-gradient-stop-schema.json	New schema for gradient stops.
features/dd-sdk-android-session-replay/src/main/json/schemas/session-replay/mobile/shape-gradient-schema.json	New schema for background gradients.
features/dd-sdk-android-session-replay/src/main/json/schemas/session-replay/mobile/shape-gradient-point-schema.json	New schema for gradient points.
features/dd-sdk-android-session-replay/src/main/json/schemas/session-replay/mobile/incremental-snapshot-record-schema.json	Adds optional slotId at record level.
features/dd-sdk-android-session-replay/src/main/json/schemas/session-replay/mobile/incremental-data-schema.json	Adds composition-tree mutation incremental data variant.
features/dd-sdk-android-session-replay/src/main/json/schemas/session-replay/mobile/full-snapshot-record-schema.json	Adds optional compositionTree under data and optional slotId at record level.
features/dd-sdk-android-session-replay/src/main/json/schemas/session-replay/mobile/embedded-content-wireframe-update-schema.json	New embedded-content wireframe update schema.
features/dd-sdk-android-session-replay/src/main/json/schemas/session-replay/mobile/embedded-content-wireframe-schema.json	New embedded-content wireframe schema.
features/dd-sdk-android-session-replay/src/main/json/schemas/session-replay/mobile/composition-tree-schema.json	New schema for composition tree in full snapshots.
features/dd-sdk-android-session-replay/src/main/json/schemas/session-replay/mobile/composition-tree-mutation-data-schema.json	New schema for composition-tree mutation incremental data.
features/dd-sdk-android-session-replay/src/main/json/schemas/session-replay/mobile/composition-layer-update-schema.json	New schema for sparse composition-layer updates.
features/dd-sdk-android-session-replay/src/main/json/schemas/session-replay/mobile/composition-layer-shadow-modifier-schema.json	New schema for shadow modifier.
features/dd-sdk-android-session-replay/src/main/json/schemas/session-replay/mobile/composition-layer-schema.json	New schema for composition layers.
features/dd-sdk-android-session-replay/src/main/json/schemas/session-replay/mobile/composition-layer-saturate-modifier-schema.json	New schema for saturate modifier.
features/dd-sdk-android-session-replay/src/main/json/schemas/session-replay/mobile/composition-layer-opacity-modifier-schema.json	New schema for opacity modifier.
features/dd-sdk-android-session-replay/src/main/json/schemas/session-replay/mobile/composition-layer-modifier-schema.json	New schema union for composition-layer modifiers.
features/dd-sdk-android-session-replay/src/main/json/schemas/session-replay/mobile/composition-layer-mask-image-modifier-schema.json	New schema for mask-image modifier.
features/dd-sdk-android-session-replay/src/main/json/schemas/session-replay/mobile/composition-layer-gaussian-blur-modifier-schema.json	New schema for gaussian blur modifier.
features/dd-sdk-android-session-replay/src/main/json/schemas/session-replay/mobile/composition-layer-color-matrix-modifier-schema.json	New schema for color matrix modifier.
features/dd-sdk-android-session-replay/src/main/json/schemas/session-replay/mobile/composition-layer-clip-modifier-schema.json	New schema for clip modifier.
features/dd-sdk-android-session-replay/src/main/json/schemas/session-replay/mobile/composition-layer-child-schema.json	New schema for layer/wireframe child references.
features/dd-sdk-android-session-replay/src/main/json/schemas/session-replay/mobile/composition-layer-brightness-bias-modifier-schema.json	New schema for brightness-bias modifier.
features/dd-sdk-android-session-replay/api/dd-sdk-android-session-replay.api	Updates API dump to include new wire-model types and config surface changes.
features/dd-sdk-android-session-replay/api/apiSurface	Updates Kotlin API surface snapshot for new/changed public symbols.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[jonathanmos]

@codex review

[datadog-prod-us1-4]

🎉 All green!

🧪 All tests passed
❄️ No new flaky tests detected

🔄 Datadog retried 1 test - 1 passed on retry

🎯 Code Coverage (details)
• Patch Coverage: 100.00%
• Overall Coverage: 72.82% (+0.00%)

_{This comment will be updated automatically if new data arrives.
🔗 Commit SHA: 737d49a | Docs | Datadog PR Page | Give us feedback!}

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 73456506bf

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: eb427f31a0

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 03a724f882

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 9250e41d84

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 1ddba935d5

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 811429dcfc

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 0ae03f715d

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 89525c0db4

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 7bad7caf3c

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".