fix(replay): stop a platform view mask spilling past its visible bounds

[turnipdabeets]

💡 Motivation and Context

Session replay masks a platform view — a map, WebView, or camera preview — by painting a black rectangle over it, because the OS draws those, not Flutter.

The rectangle was sized from the view's full bounds, ignoring that a ClipRect or a scroll viewport may only be showing part of it. So the mask ran past the view and covered whatever Flutter widgets sat outside that clip, and those widgets disappeared from replay. Revealed views (PostHogPlatformViewPrivacy.capture) composited past the clip the same way.

The mask is now intersected with the ancestor clip chain, and a revealed view is clipped to the same region when it is composited. Masked regions are correspondingly smaller: content a clipped platform view never actually showed on screen is no longer covered.

Also fixed on the same path:

• A revealed view whose native capture fails fell back to masking its full frame — the same oversized mask. It now masks only the visible region.
• A CustomClipper that throws let the exception escape and the view lost its mask entirely.
• A perspective ancestor transform (a ListWheelScrollView, so any CupertinoPicker) could shrink the mask or drop it, because mapping a rect by its four corners only over-approximates for affine matrices.
• A pinned sliver header made the viewport report a clip smaller than the one it paints with, leaving the band under a translucent header unmasked.
• A platform view cached but scrolled off-screen (inside a ListView's cacheExtent) got a full-size black rectangle at a position entirely outside the viewport. It is now dropped.

Scope

This clips platform-view masks. The widget-mask path (PostHogMaskWidget, maskAllTexts, maskAllImages) still uses unclipped paint bounds and can still spill across a clip edge — same helper, different call sites, and it changes every mask on every screen, so it wants its own PR and its own device matrix.

💚 How did you test it?

example/lib/platform_view_spill_screen.dart ships in this PR and is reachable from the example app's menu, so the matrix below can be re-run. It has two families of case:

• Spill (1–7) — a sentinel banner sits directly below a clipped platform view. The banner is plain Flutter, so replay must always show it; a missing banner means the mask overran. Scored by counting the banner's pixels in the captured replay frame.
• Orientation (8–11) — a revealed view shows four coloured quadrants. Native crops an axis-aligned region, so replay must put the same quadrant in the same corner as the screen. Scored by comparing the replay frame against a device screenshot taken at the same moment.

Results

Sentinel cases report the banner's pixel count in the replay frame (0 = buried by the mask). Orientation cases report which quadrant sits in each corner, replay vs screen.

origin/main → this PR

case	Android main	Android, this PR	iOS main	iOS, this PR
1 clipped, masked	0 — buried	35,256	0 — buried	34,236
2 scrolled, masked	35,164	35,164	34,196	34,196
3 nested clips, masked	0 — buried	34,740	0 — buried	33,796
4 clipped, revealed	34,852	34,976	0 — buried	33,924
5 scrolled, revealed	35,192	35,192	34,272	34,272
6 masked over revealed	0 — buried	35,388	0 — buried	34,384
7 unclipped control	34,776	34,776	33,720	33,720
8 revealed, no transform	match	match	match	match
9 revealed, quarter turn	match	match	mismatch	mismatch (unchanged)
10 revealed, mirrored	match	match	mismatch	mismatch (unchanged)
11 revealed, turned + clipped	match	match	native reveal fails → mask	→ mask, now correctly clipped
total	8/11	11/11	4/11	8/11

Every case the fix targets goes from 0 px to a fully visible banner, and the unclipped control (7) and the unclipped scrolled cases (2, 5) are unchanged to the pixel on both platforms.

The two platforms crop in different spaces

Worth knowing for anyone touching this code again, because it is not visible from the Dart side:

• Android's PixelCopy crops the screen. The returned pixels already show the view rotated, so they must go back into the device-space rect.
• iOS snapshots a WKWebView in the view's own space. The returned pixels are always unrotated, so a rotated revealed view composites unrotated — on main and here alike.

An intermediate revision of this branch drew the crop in the view's own space. That cancelled out iOS's view-space snapshot (making iOS look better, 10/11) while double-rotating on Android (8/11 — case 9 replay MYBR against screen YRMB). The orientation cases caught it and it is reverted.

iOS cases 9–11 are therefore a pre-existing gap this PR neither touches nor regresses — the same result as main. Tracking separately.

Unit tests

333 pass. The clip walk is covered directly — a scrolled view with a non-zero origin, nested clips, a throwing clipper against a non-throwing control, Clip.none, non-finite rects, perspective ancestors, a pinned sliver header, and full clip-away. The composite is covered with picture-recorder pixel tests, including a 45° turn (a quarter turn cannot tell the view-space clip apart from its device-space hull) and the capture-failure fallback.

Every line that produces the fix was checked by mutating it and confirming a test fails: the masked rect, the fully-clipped drop, the revealed view's visible region, the fallback mask, and the view-space clip.

flutter analyze and dart format are clean on both the SDK and the example.

📝 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: Human-driven (agent-assisted)

Claude Code drove seven review→triage→fix cycles against the shared SDK review criteria, plus the device matrices above.

Decisions worth flagging for a reviewer:

• The native request deliberately still sends the view's full bounds. Shrinking it to the visible rect looks like the obvious optimisation, but iOS only reveals a web view whose window frame the crop rect fully contains (so a neighbouring masked web view cannot be snapshotted). Clipping happens on the Dart side at paint time instead.
• A translucent pinned sliver header leaves a band unmasked. The viewport reports a clip that excludes the band an overlapping header covers. Masking it would black an opaque header out of the replay — a certain regression — to prevent a leak two device rounds could not reproduce. Documented in the code.
• A motion-compensation mechanism was written, then deleted once tracing showed there are no awaits between rect collection and mask painting, so it could never have done anything.
• A sliver-overlap branch was written, then deleted as unreproducible rather than shipped on speculation.

[github-actions]

posthog-flutter Compliance Report

Date: 2026-08-28 16:11:07 UTC
Duration: 96780ms

✅ All Tests Passed!

45/45 tests passed

---

Capture Tests

✅ 29/29 tests passed

View Details

Test	Status	Duration
Format Validation.Event Has Required Fields	✅	140ms
Format Validation.Event Has Uuid	✅	121ms
Format Validation.Event Has Lib Properties	✅	116ms
Format Validation.Distinct Id Is String	✅	115ms
Format Validation.Token Is Present	✅	114ms
Format Validation.Custom Properties Preserved	✅	116ms
Format Validation.Event Has Timestamp	✅	117ms
Retry Behavior.Retries On 503	✅	5332ms
Retry Behavior.Does Not Retry On 400	✅	2117ms
Retry Behavior.Does Not Retry On 401	✅	2117ms
Retry Behavior.Respects Retry After Header	✅	8122ms
Retry Behavior.Implements Backoff	✅	15446ms
Retry Behavior.Retries On 500	✅	5226ms
Retry Behavior.Retries On 502	✅	5225ms
Retry Behavior.Retries On 504	✅	5224ms
Retry Behavior.Max Retries Respected	✅	15444ms
Deduplication.Generates Unique Uuids	✅	123ms
Deduplication.Preserves Uuid On Retry	✅	5224ms
Deduplication.Preserves Uuid And Timestamp On Retry	✅	10334ms
Deduplication.Preserves Uuid And Timestamp On Batch Retry	✅	5230ms
Deduplication.No Duplicate Events In Batch	✅	123ms
Deduplication.Different Events Have Different Uuids	✅	116ms
Compression.Sends Gzip When Enabled	✅	115ms
Batch Format.Uses Proper Batch Structure	✅	113ms
Batch Format.Flush With No Events Sends Nothing	✅	108ms
Batch Format.Multiple Events Batched Together	✅	123ms
Error Handling.Does Not Retry On 403	✅	2116ms
Error Handling.Does Not Retry On 413	✅	2117ms
Error Handling.Retries On 408	✅	5223ms

Feature_Flags Tests

✅ 16/16 tests passed

View Details

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

[veria-ai]

PR overview

All previously flagged issues have been addressed. No open security concerns remain on this pull request.

Security review

No open security issues remain on this pull request.

Fixed/addressed: 3 · PR risk: 0/10

[greptile-apps]

Security Review

Two privacy-boundary problems remain: approximate CustomClipper bounds can under-mask native content, and affine rotated or skewed clips can composite revealed pixels outside the actual clip.

Prompt To Fix All With AI

### Issue 1
posthog_flutter/lib/src/replay/screenshot/screenshot_capturer.dart:883
**Approximate clips under-mask content**

When a `CustomClipper` reports an approximate rectangle smaller than its actual paint clip, `describeApproximatePaintClip` limits the mask to that smaller region, causing native pixels between the approximate and painted clips to remain visible in replay.

**How this was verified:** The changed masked branch paints only the `visible` rectangle returned through `describeApproximatePaintClip`, while the added documentation explicitly states that this rectangle can be smaller than `getClip`.

### Issue 2
posthog_flutter/lib/src/replay/screenshot/screenshot_capturer.dart:907
**Affine clips reveal pixels**

When a captured platform view is clipped through an affine rotation or skew, `transformRect` reduces the non-axis-aligned clip to its bounding rectangle and compositing reuses that approximation, causing native pixels outside the actual clip to be drawn over unrelated Flutter content.

**How this was verified:** The code bypasses rectangle mapping only for projective transforms, then clips the full native crop using the affine clip's axis-aligned bounding rectangle.

### Issue 3
posthog_flutter/lib/src/replay/screenshot/screenshot_capturer.dart:888-890
**Opaque headers lose pixels**

When a platform view scrolls beneath an opaque pinned sliver header, replacing the viewport's overlap-aware clip with its full size includes the covered band, causing masks to black out the header or captured native pixels to be composited over it.

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

_{Reviews (1): Last reviewed commit: "fix(replay): mask the band a pinned sliv..." | Re-trigger Greptile}

[ioannisj]

Should this catch fail closed? Right now it adds the view to neither masked nor captured, so a throw anywhere in the walk drops the mask for that frame.

That's the opposite direction from the catch inside clippedPaintBounds, which skips a failing clip on purpose so the wider bounds survive.

It bites hardest for a TextureBox under privacy: mask: its pixels are already in the toImage() snapshot by the time this runs, so no mask entry means the live camera frame ships in the replay. Pushing ro.paintBounds into masked here when the policy isn't capture would widen the mask instead of removing it. Is there a reason not to?

[turnipdabeets]

Good catch — you're right, and it's fixed in ab2d30f.

I wanted to be sure of your TextureBox premise before changing the failure direction, since this file asserts it in a comment but nobody had measured it. It holds. I built a throwaway app with a real texture producer on each platform (Android createSurfaceProducer() + a lockCanvas loop, iOS a FlutterTexture vending a CVPixelBuffer), painted a colour that cycles so a live frame is distinguishable from a stale one, wrapped it in a RepaintBoundary and read back toImage():

	texture centre	control
Android, Impeller	(255,104,255) then (255,184,255)	(0,255,0)
Android, Skia	(255,104,255) then (255,184,255)	(0,255,0)
iOS 26.4 sim	(255,120,255) then (255,0,255)	(0,255,0)

Live texture pixels, not background, and the green channel advanced in step with the producer. The engine reason is that TextureLayer::Paint looks the texture up in the registry and draws it into the canvas (flow/layers/texture_layer.cc), and LayerTree::Flatten passes that registry into the offscreen paint context behind Scene::toImage — whereas PlatformViewLayer has no paint of its own and is an embedder-composited hole. So a masked TextureBox with no mask entry does ship a live camera frame.

On the fix direction: I went with dropping the frame rather than pushing ro.paintBounds into masked. The only thing that realistically throws in that block is ro.getTransformTo(ancestor) (object.dart:3696, "not in the same render tree"), and it's the first statement — so when we land in the catch we have no transform, and a mask rect without one is placed in the wrong coordinate space. Masking the wrong region would leave the real region exposed, which is the same leak with extra steps.

Dropping the frame is also what the widget mask walk two functions up already does when getMaskElements returns null, so the two paths now fail the same way. A revealed view still just skips — it has no mask to lose.

I deliberately did not narrow the drop to TextureBox only. Android TLHC platform views are texture-backed too and surface as PlatformViewRenderBox, and I have not confirmed whether their pixels reach toImage(), so treating every masked platform view the same avoids resting on an open question. The trigger needs the view and the container to be in different render trees, so frames should rarely drop in practice.

Regression test in platform_view_rects_test.dart measures against a detached RenderObject to force the real throw; mask policy returns null (frame dropped), capture policy still returns rects. Checked non-vacuous — reverting the catch to the old always-continue behaviour fails it. 334 tests pass.