feat(replay): add opt-in custom-paint masking

[marandaneto]

💡 Motivation and Context

Related to #568.

Session replay masks ordinary text but does not mask text drawn by a CustomPainter. Masking every custom painter by default would also hide Flutter decorations and could cover large parts of the screen.

This PR adds PostHogSessionReplayConfig.maskCustomPaint, defaulting to false. Apps can opt in with:

config.sessionReplayConfig.maskCustomPaint = true;

The option works independently of maskAllTexts and maskAllImages, including when both are disabled. When enabled, it masks the full bounds of CustomPaint widgets with a painter or foreground painter, including their children. Painter-less containers still allow their children to be checked normally. The flag is used by both Flutter screenshot capture and the web mask-region provider.

Default masking behavior remains unchanged. The docs clarify that custom-painted text and images require this option or an explicit PostHogMaskWidget. Enabling the option can mask decorations too. Flutter's debug banner uses a full-window CustomPaint, so the docs recommend disabling debugShowCheckedModeBanner when using this option.

💚 How did you test it?

• Reproduced over-masking on the previous PR head with a failing test that expects custom-painted content to remain visible by default.
• Verified the new option independently of text and image masking, including foreground painters, explicit masks, painter-less containers, transforms, and screenshot pixels.
• All 365 Flutter tests passed.
• All 77 focused Chrome tests passed. The native-only screenshot capture test is skipped on Chrome. Separate tests verify the web mask-region provider and its warning when masking is requested without a provider.
• All 25 focused tests passed on an Android 16 emulator, including the native screenshot capture path with only maskCustomPaint enabled. A temporary app used a fake PostHog platform interface and mocked replay-state calls, so no events were sent to PostHog.
• Static analysis, formatting, the public API snapshot check, and git diff --check passed.
• Autoreview of commit a440e0af45e1b07aed9b549f6996386636811f28 against origin/main reported no actionable findings.

📝 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

• Added a minor changeset for the new configuration option.

🤖 Agent context

Autonomy: Human-driven (agent-assisted)

Pi implemented this feature using file tools, Git, Flutter tests, Chrome, an Android emulator, and the autoreview helper. The work was directed by @marandaneto and done in a dedicated worktree.

The initial implementation masked custom painters whenever text or image masking was enabled. After reviewing the risk of hiding non-sensitive UI, the human owner requested an independent maskCustomPaint option defaulting to false. Human review is required.

[github-actions]

posthog-flutter Compliance Report

Date: 2026-09-11 10:39:42 UTC
Duration: 96897ms

✅ All Tests Passed!

45/45 tests passed

---

Capture Tests

✅ 29/29 tests passed

View Details

Test	Status	Duration
Format Validation.Event Has Required Fields	✅	149ms
Format Validation.Event Has Uuid	✅	120ms
Format Validation.Event Has Lib Properties	✅	117ms
Format Validation.Distinct Id Is String	✅	115ms
Format Validation.Token Is Present	✅	116ms
Format Validation.Custom Properties Preserved	✅	117ms
Format Validation.Event Has Timestamp	✅	118ms
Retry Behavior.Retries On 503	✅	5332ms
Retry Behavior.Does Not Retry On 400	✅	2118ms
Retry Behavior.Does Not Retry On 401	✅	2120ms
Retry Behavior.Respects Retry After Header	✅	8126ms
Retry Behavior.Implements Backoff	✅	15447ms
Retry Behavior.Retries On 500	✅	5228ms
Retry Behavior.Retries On 502	✅	5227ms
Retry Behavior.Retries On 504	✅	5225ms
Retry Behavior.Max Retries Respected	✅	15449ms
Deduplication.Generates Unique Uuids	✅	126ms
Deduplication.Preserves Uuid On Retry	✅	5226ms
Deduplication.Preserves Uuid And Timestamp On Retry	✅	10336ms
Deduplication.Preserves Uuid And Timestamp On Batch Retry	✅	5229ms
Deduplication.No Duplicate Events In Batch	✅	125ms
Deduplication.Different Events Have Different Uuids	✅	118ms
Compression.Sends Gzip When Enabled	✅	117ms
Batch Format.Uses Proper Batch Structure	✅	116ms
Batch Format.Flush With No Events Sends Nothing	✅	109ms
Batch Format.Multiple Events Batched Together	✅	126ms
Error Handling.Does Not Retry On 403	✅	2118ms
Error Handling.Does Not Retry On 413	✅	2118ms
Error Handling.Retries On 408	✅	5225ms

Feature_Flags Tests

✅ 16/16 tests passed

View Details

Test	Status	Duration
Request Payload.Request With Person Properties Device Id	✅	14ms
Request Payload.Flags Request Uses V2 Query Param	✅	10ms
Request Payload.Flags Request Hits Flags Path Not Decide	✅	9ms
Request Payload.Flags Request Omits Authorization Header	✅	10ms
Request Payload.Token In Flags Body Matches Init	✅	10ms
Request Payload.Groups Round Trip	✅	10ms
Request Payload.Groups Default To Empty Object	✅	10ms
Request Payload.Person Properties Distinct Id Auto Populated When Caller Omits It	✅	10ms
Request Payload.Disable Geoip False Propagates As Geoip Disable False	✅	10ms
Request Payload.Disable Geoip Omitted Defaults To False	✅	9ms
Request Payload.Flag Keys To Evaluate Contains Only Requested Key	✅	10ms
Request Lifecycle.No Flags Request On Init Alone	✅	4ms
Request Lifecycle.No Flags Request On Normal Capture	✅	114ms
Request Lifecycle.Two Flag Calls Produce Two Remote Requests	✅	17ms
Request Lifecycle.Mock Response Value Is Returned To Caller	✅	9ms
Side Effect Events.Get Feature Flag Captures Feature Flag Called Event	✅	115ms

[greptile-apps]

_{Reviews (1): Last reviewed commit: "feat(replay): make custom-paint masking ..." | Re-trigger Greptile}

[marandaneto]

Validated commit a440e0af45e1b07aed9b549f6996386636811f28 on an Android 16 (API 36) emulator. All 28 tests passed.

The tests exercised the actual Flutter screenshot capture and masking path and checked the resulting replay image pixels:

• With default settings, custom-painted text remains visible while ordinary text is masked.
• With maskCustomPaint: true, the custom-painted area is masked.
• With maskAllTexts and maskAllImages both disabled, maskCustomPaint: true still masks the custom-painted area.
• After disabling maskCustomPaint again, the captured image is byte-identical to the default-settings image.
• Unrelated areas remain visible.

The run also covered foreground painters, flag combinations, explicit masks, painter-less containers, transforms, and the debug-banner behavior when opted in.

This used a temporary integration-test app against the PR worktree. PostHog platform calls and replay-state responses were mocked, so no events were sent to PostHog. This validates on-device rendering and screenshot masking, not ingestion or playback in the PostHog UI.