feat(replay): mask canvas session replay recordings on Flutter web

[turnipdabeets]

💡 Motivation and Context

Fixes #496 — on Flutter web, session replay is posthog-js canvas capture, and the entire app (including PII text) is pixels inside the CanvasKit canvas. DOM-based masking can't see it, and sessionReplayConfig.maskAllTexts/maskAllImages were silent no-ops on web.

Depends on PostHog/posthog-js#4270 — draft until that ships in a release. On older posthog-js this PR degrades to current behavior (no masking); before releasing, the posthog-js minimum version gate/warning must be filled in with the release number.

setup() (web, when config.sessionReplay is true) registers a mask-region provider with posthog-js via set_config:

• Rect computation reuses the mobile masking logic — one widget-tree walk (PostHogMaskController.getMaskElements, new single-walk method) with the exact selection rules mobile uses: maskAllTexts/maskAllImages gate the full text/image sets; PostHogMaskWidget and obscured text fields always mask. Rects are transform-aware (AABB for rotated/scaled widgets), outset 1px, converted to canvas-relative CSS px against the flutter-view host rect (correct for embedded/offset views), and cached per Flutter frame (recompute only when a frame was painted — idle cost ≈0.01ms/call, measured).
• posthog-js paints the regions black inside its capture pipeline before frames are encoded — masked pixels never leave the browser.
• Fail-closed: a failed widget-tree walk returns a full-canvas mask (with a one-time console warning after ~10 consecutive failures explaining the PostHogWidget requirement); with requireMaskProvider set in the posthog.init HTML config, frames captured before Flutter boots are blacked out; non-Flutter canvases get no regions (identity-checked via the flutter-view host chain).
• Accessibility side-channel closed: with a11y active, Flutter mirrors widget text into flt-semantics DOM nodes as plain text, which rrweb records; the provider forwards blockSelector: 'flt-semantics-host' (merged with any user selector). Reproduced and verified gone.
• Lifecycle: posthog-js reads blockSelector/requireMaskProvider only at rrweb record() start, so an in-flight recording is restarted once after registration (same session id; sampling decision persists). Registration retries with backoff (250ms→4s, 2min cap) until posthog-js is available — covering both the snippet stub being replaced by the real instance and posthog-js loading after Flutter entirely.

No new public Dart API (package barrel diff is zero lines). Existing config options and PostHogMaskWidget simply start working on web, with mobile-identical semantics.

💚 How did you test it?

• flutter analyze clean; VM tests 7/7 (geometry incl. rotation AABB + degenerate rects; single-walk equivalence vs the two-walk union); browser tests 11/11 (--platform chrome, wired into CI): set_config merge preserving user config, fail-closed full-cover for a flutter-view canvas without PostHogWidget, warn-once on persistent walk failure, foreign-canvas exclusion, semantics blockSelector with maskAllTexts=false, deferred registration + stub-replacement convergence (incl. posthog-js absent entirely at setup), restart-exactly-once.
• End-to-end against the posthog-js branch from feat(replay): canvas mask regions for session replay canvas capture posthog-js#4270: wire-level canvas frames inspected at before_send (all text masked incl. scaled/rotated, images honoring maskAllImages; wrapper-only tier verified — exactly the wrapped/obscured widgets masked), and real recordings played + backward-scrub-tested in the production PostHog player.
• Perf: cold walk measured at ~20µs per masked text node (200 widgets ≈ 4.4ms, 1000 ≈ 20.5ms, chrome/debug); per-frame cache makes steady-state ≈0.01ms. O(N) walk optimization (shared with mobile) is a measured follow-up.

Known limitations (documented in CHANGELOG; docs PR to follow): CustomPainter-drawn text isn't in the widget tree → not masked (same as mobile; PostHogMaskWidget is the escape hatch); requires config.sessionReplay = true and PostHogWidget wrapping the app — without the widget, masking fails closed (black frames) by design.

📝 Checklist

• I reviewed the submitted code.
• I added tests to verify the changes.
• I updated the docs if needed. (CHANGELOG updated; posthog.com docs PR drafted, to land with the releases.)
• No breaking change or entry added to the changelog.

If releasing new changes

• Changeset: CHANGELOG ## Next entry added (repo convention).

🤖 Agent context

Autonomy: Human-driven (agent-assisted)

Built with Claude Code from the investigation of #496 (transferred from PostHog/posthog#66291). The provider deliberately reuses the mobile masking walk rather than a parallel implementation, so web and mobile masking semantics cannot drift. Notable findings fixed during pre-PR review loops (several with executed repros): posthog-js replaces the snippet stub rather than upgrading it (retry must re-read window.posthog), set_config against the stub would wipe user session_recording config, start-time-only options require the one-time recording restart, and the a11y semantics tree leaks widget text as DOM text nodes. E2E verification was performed against the sibling posthog-js branch with wire-level frame inspection and the production replay player.

🤖 Generated with Claude Code

[github-actions]

posthog-flutter Compliance Report

Date: 2026-07-25 16:09:07 UTC
Duration: 96894ms

✅ All Tests Passed!

45/45 tests passed

---

Capture Tests

✅ 29/29 tests passed

View Details

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

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	✅	11ms
Request Payload.Flags Request Hits Flags Path Not Decide	✅	10ms
Request Payload.Flags Request Omits Authorization Header	✅	11ms
Request Payload.Token In Flags Body Matches Init	✅	10ms
Request Payload.Groups Round Trip	✅	12ms
Request Payload.Groups Default To Empty Object	✅	10ms
Request Payload.Person Properties Distinct Id Auto Populated When Caller Omits It	✅	12ms
Request Payload.Disable Geoip False Propagates As Geoip Disable False	✅	11ms
Request Payload.Disable Geoip Omitted Defaults To False	✅	10ms
Request Payload.Flag Keys To Evaluate Contains Only Requested Key	✅	12ms
Request Lifecycle.No Flags Request On Init Alone	✅	5ms
Request Lifecycle.No Flags Request On Normal Capture	✅	114ms
Request Lifecycle.Two Flag Calls Produce Two Remote Requests	✅	18ms
Request Lifecycle.Mock Response Value Is Returned To Caller	✅	10ms
Side Effect Events.Get Feature Flag Captures Feature Flag Called Event	✅	118ms