fix(replay): warn when wireframe capture cannot record a Compose window

[posthog]

💡 Motivation and Context

• Every Jetpack Compose app that turns on session replay with the shipped defaults records a blank gray screen, and nothing in the SDK says why. The developer's only route to the answer today is a support ticket.
• sessionReplayConfig.screenshot defaults to false, so capture builds a wireframe. View.toWireframe() only walks classic View types (TextView, ImageView, Spinner, ViewGroup), and a Compose-rooted window contains none of them, so the tree comes back essentially empty.
• The SDK already detects a Compose root (isComposeView() / containsComposeView() / WindowDrawState.composeRooted), but that detection only fed the screenshot mask path. On the wireframe path it logged nothing and changed nothing.

  // PostHogSessionReplayConfig
- screenshot = false   // wireframe capture: classic Views only -> blank on Compose, silently
+ screenshot = false   // same default, but the SDK now says when it cannot record the screen

Window	Capture mode	Before	After
Classic Views	wireframe	records	records, no new log
Compose	wireframe	blank, silent	blank, one warning naming sessionReplayConfig.screenshot = true
Compose	screenshot	records	records, unchanged

Changes

• generateSnapshot() now calls warnIfComposeWireframe() on the wireframe branch. It reads the cached Compose-root verdict; when that is unknown it resolves it inline on the main thread, or posts the check without waiting when called from the capture executor and reads the result on the next snapshot. The capture thread never blocks for this log line.
• The check only runs while debug logging is on (the guard reads logger.isEnabled() first), and a "not Compose" verdict is re-checked after a layout at most once per second, so a classic-View app with debug on pays a small bounded walk and nothing with debug off.
• The warning fires once per process, guarded by an AtomicBoolean that is read before the Compose check, so a warned process never pays for the check again.
• Capture behaviour is unchanged. The mode is not switched automatically: screenshots can show content the mask rules do not cover, so that stays an explicit opt-in.
• KDoc on screenshot, maskAllTextInputs and maskAllImages now states the wireframe limit and that masking applies to both modes.

💚 How did you test it?

• Two new Robolectric tests in PostHogReplayIntegrationTest: a Compose-rooted window warns exactly once over two snapshots, and a classic-View window stays quiet.
• Verified the test is real: with the one-line call removed, wireframe capture warns once about a compose rooted window fails; with it restored it passes.
• Ran the full :posthog-android:testReleaseUnitTest suite and spotlessCheck. Both pass.
• Not tested on a device or emulator, and no sample app run. The blank-recording symptom itself is not re-proved here; it follows from View.toWireframe() covering only classic View types and is the same failure mode addressed for screenshot mode in fix(replay): keep Compose screenshots by routing them onto the verified mask path #713.

📝 Checklist

• I reviewed the submitted code.
• I added tests to verify the changes.
• I updated the docs if needed.
• No breaking change or entry added to the changelog.

If releasing new changes

• Ran pnpm changeset to generate a changeset file

🤖 Agent context

Autonomy: Fully autonomous

• Written by Claude Opus 5 in PostHog Desktop, from an inbox report about blank Compose session recordings. Tools used: shell (gradle, git), file read/edit, GitHub CLI.
• Considered switching to screenshot capture automatically when a Compose root is found. Rejected it: it changes what leaves the device without the developer asking, and screenshot capture is opt-in for that reason. A warning gives the same information and leaves the choice with the app.
• Placed the check in generateSnapshot() rather than at install time, because a Compose root can be mounted lazily and is only known from the live view tree.
• The environment had no JDK and no Android SDK; both were installed to run the test suite.

---

Created with PostHog Desktop from this inbox report.

[posthog]

🦔 PostHog Review reviewed this pull request

Found 0 must fix, 1 should fix, 1 consider.

Published 2 findings (view the review).

Resolved comments: 2 fixed

[posthog]

PostHog Review alpha 🦔 If you find any issues helpful - please reply "valid", "invalid", etc., for evaluation purposes 🙏

[posthog]

PostHog Review

Found 1 should fix, 1 consider.

[marandaneto]

if our goal is to deprecate wireframes, is it worth doing this? maybe a single warning if screenshot is disabled and its a jetpack compose app check would be enough?