feat(replay): PostHogMaskWidget enables web canvas masking on its own

[turnipdabeets]

Stacked on #499 (feat/web-canvas-masking) — this PR targets that branch, not main. Review it after #499, or squash the two together before merging; they are one feature.

💡 Motivation and Context

#499 gives Flutter web canvas masking, but it only registers the mask-region provider with posthog-js when the app already declared session_recording.canvasCapture.maskRegionsFn in its posthog.init call.

That leaves a footgun: a developer wraps sensitive UI in PostHogMaskWidget, does not also edit web/index.html, and gets zero masking on web, silently. PostHogMaskWidget is the most explicit possible statement of "never record this", and it needs no setup at all on iOS and Android — so web quietly diverging is the worst possible failure mode.

The gate itself is not wrong. Registering does two things beyond attaching a function: it adds blockSelector: 'flt-semantics-host' (so Flutter's accessibility DOM is not recorded in the clear), and it restarts an in-flight recording, because posthog-js only reads those options when rrweb's record() starts. Imposing that on every Flutter web app — including ones that never asked for masking — is not acceptable.

So this PR adds a second way to opt in rather than removing the gate: a mounted PostHogMaskWidget is itself the opt-in.

🔨 What changed

• PostHogMaskWidgetState.initState calls notifyMaskWidgetMounted(), resolved through a conditional import (canvas_mask_registration_io.dart / ..._web.dart). Off web it is an empty function body, so no web code reaches mobile builds and nothing changes on iOS/Android/macOS.
• On web the hook defers to the end of the frame and calls WebCanvasMaskProvider.notifyMaskWidgetMounted(). Deferring matters: registration restarts the recording, and rrweb can take a canvas snapshot from inside that call — which would walk a widget tree that is still being built.
• WebCanvasMaskProvider keeps the same "did the app declare it?" gate, but now also applies when a mask widget has mounted. The retry/apply path became a small state machine (applied / notOptedIn / posthogNotReady) so that "posthog-js is up but the app did not opt in" parks instead of terminating — a PostHogMaskWidget mounting later re-enters it. Registration is idempotent: at most one set_config and at most one recording restart, however many mask widgets mount, and whether posthog-js loads before or after Flutter.

Apps with no PostHogMaskWidget and no declaration are still completely untouched: no set_config, no blockSelector, no restart.

Also drops a stale caveat from the example app: test 15's section title claimed PostHogMaskWidget with multiple children "needs maskAllTexts or maskAllImages". It does not, on either platform — getMaskElements calls extractMaskWidgetRects() unconditionally on web, and screenshot_capturer calls getPostHogWidgetWrapperElements() outside the flags branch on mobile (post-#500). A browser check against the built app on feat/web-canvas-masking with maskAllTexts: false, maskAllImages: false confirmed it: the provider returned a full-width rect covering the whole Row, amber box included.

⚠️ Cost and residual caveats

These are documented in the CHANGELOG and in the PostHogMaskWidget dartdoc:

• One mount enables the whole masking configuration, not just the wrapped subtree: maskAllTexts/maskAllImages default to true, so a single PostHogMaskWidget turns on full text and image canvas masking — the same semantics as mounting one on iOS/Android.
• The recording restarts once, mid-session, the first time a mask widget mounts. The replay will show a split at that point. Unavoidable without a posthog-js change: blockSelector is a start-time option.
• Frames captured before the first mount are recorded unmasked. Declaring maskRegionsFn: () => null in posthog.init is still the only thing that covers the window between page load and Flutter booting (those frames are skipped instead), and it also avoids the restart. The HTML setup is now an optimization, not a requirement.
• PostHogWidget is still required. An app that mounts a PostHogMaskWidget but is not wrapped in PostHogWidget now fails closed — canvas frames are skipped rather than recorded unmasked, with a console warning explaining the fix. That is the correct behavior for something that explicitly asked for masking, but it is a behavior change for that (misconfigured) shape of app. The outside-tree check runs once, at the mask widget's first mount: a mask widget that mounts before any PostHogWidget exists is treated as this no-PostHogWidget shape and does opt in (documented in the changeset, pinned by a test).

By design: registration does not wait on recordCanvas

Registration opts in without first checking that canvas capture is actually enabled. That is deliberate, for two reasons:

• Gating on it would fail open. recordCanvas can arrive from remote config after posthog.init, so a ph.config check at registration time can read "canvas off" for a session that goes on to record the canvas — masking would silently never attach.
• Registration earns its keep even with canvas capture off. Applying the config also installs blockSelector: 'flt-semantics-host', and that exclusion is independent of the canvas: with accessibility active, Flutter mirrors widget text into flt-semantics DOM nodes, which rrweb records as plaintext during ordinary DOM recording. So a canvas-off app that mounts a PostHogMaskWidget still gains a real thing — the a11y text side-channel is closed.

The restart is gated on ph.sessionRecordingStarted() regardless, so an app that is not recording pays nothing at all.

💚 How did you test it?

Three new tests in test/web_canvas_mask_provider_test.dart (already listed in the "Test (web)" CI job, so no workflow change needed):

• a mounted PostHogMaskWidget opts the app in when posthog.init declared nothing — provider attached, blockSelector set, recording restarted once;
• exactly one set_config and one restart across two pumps with three and then five mask widgets;
• a mask widget that mounts while posthog-js is still absent opts in as soon as posthog-js appears.

A follow-up commit (review fixes, merged with the updated #499 base) adds two more: cross-path idempotency (app opted in via the init declaration, then a mask widget mounts — still exactly one set_config and one restart), and a set_config throw during the mount-triggered apply being retried and applied on a later tick instead of permanently consuming the opt-in.

The pre-existing leaves posthog-js untouched when the app declares no mask provider test is unchanged and still passing, which is the assertion that apps opting into nothing stay untouched.

Ran locally, all green:

• flutter test — 247 passing
• flutter test --platform chrome test/posthog_flutter_web_handler_test.dart test/web_canvas_mask_provider_test.dart — 46 passing
• flutter analyze — no issues
• dart format --output=none --set-exit-if-changed ./ — exit 0

The registration change itself was not manually verified in a browser against a real posthog-js build; the posthog-js side of the contract is exercised by the stub, as in #499. The test 15 measurement quoted above was taken by hand on the base branch, not by the agent.

📝 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

• Release note shipped as a one-line changeset (.changeset/mask-widget-web-canvas.md) per the changelog style; the behavioral detail (whole-config opt-in, one-time restart, pre-mount window, PostHogWidget requirement, mount-time outside-tree check) lives in this PR body and the PostHogMaskWidget dartdoc.

🤖 Agent context

Autonomy: Human-driven (agent-assisted)

Written with Claude Code (Opus 5). The design question was how to let shared widget code trigger web-only registration without leaking dart:js_interop into mobile builds; the repo's existing _io.dart / _web.dart conditional-import convention (see origin.dart, chunk_ids.dart) handles it, so the mount hook is a one-line no-op function on every non-web platform.

Two alternatives were rejected: removing the gate outright (would restart recording and drop the semantics tree for every Flutter web app, including ones that never asked for masking), and gating registration on recordCanvas being visibly enabled in ph.config (fails open when canvas capture arrives via remote config, and would forfeit the semantics exclusion for canvas-off apps — see "By design" above).

Deferring the hook to a post-frame callback was a deliberate change after the first working version called it synchronously from initState — registering synchronously means posthog-js may re-enter the mask-region provider mid-build, which walks the render tree.

[github-actions]

posthog-flutter Compliance Report

Date: 2026-07-30 14:42:47 UTC
Duration: 96756ms

✅ All Tests Passed!

45/45 tests passed

---

Capture Tests

✅ 29/29 tests passed

View Details

Test	Status	Duration
Format Validation.Event Has Required Fields	✅	136ms
Format Validation.Event Has Uuid	✅	118ms
Format Validation.Event Has Lib Properties	✅	115ms
Format Validation.Distinct Id Is String	✅	114ms
Format Validation.Token Is Present	✅	113ms
Format Validation.Custom Properties Preserved	✅	116ms
Format Validation.Event Has Timestamp	✅	115ms
Retry Behavior.Retries On 503	✅	5329ms
Retry Behavior.Does Not Retry On 400	✅	2117ms
Retry Behavior.Does Not Retry On 401	✅	2117ms
Retry Behavior.Respects Retry After Header	✅	8124ms
Retry Behavior.Implements Backoff	✅	15446ms
Retry Behavior.Retries On 500	✅	5225ms
Retry Behavior.Retries On 502	✅	5226ms
Retry Behavior.Retries On 504	✅	5220ms
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	✅	5226ms
Deduplication.No Duplicate Events In Batch	✅	121ms
Deduplication.Different Events Have Different Uuids	✅	115ms
Compression.Sends Gzip When Enabled	✅	116ms
Batch Format.Uses Proper Batch Structure	✅	115ms
Batch Format.Flush With No Events Sends Nothing	✅	108ms
Batch Format.Multiple Events Batched Together	✅	122ms
Error Handling.Does Not Retry On 403	✅	2115ms
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	✅	8ms
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	✅	9ms
Request Payload.Groups Round Trip	✅	9ms
Request Payload.Groups Default To Empty Object	✅	9ms
Request Payload.Person Properties Distinct Id Auto Populated When Caller Omits It	✅	9ms
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	✅	9ms
Request Lifecycle.No Flags Request On Init Alone	✅	4ms
Request Lifecycle.No Flags Request On Normal Capture	✅	111ms
Request Lifecycle.Two Flag Calls Produce Two Remote Requests	✅	15ms
Request Lifecycle.Mock Response Value Is Returned To Caller	✅	9ms
Side Effect Events.Get Feature Flag Captures Feature Flag Called Event	✅	114ms

[greptile-apps]

Security Review

A failed recording stop can leave the provider marked as applied even though the semantics exclusion never took effect, allowing accessibility DOM text to remain visible to session recording.

Prompt To Fix All With AI

### Issue 1
posthog_flutter/lib/src/replay/web/web_canvas_mask_provider.dart:246
**Applied state precedes restart**

When `stopSessionRecording()` throws after `set_config` succeeds, `_applied` remains true and later attempts skip the restart required for `blockSelector`, causing Flutter accessibility text to continue being recorded in plaintext. **How this was verified:** `_applied` is assigned before the stop/start calls, while the adjacent code documents that the selector only takes effect when recording starts.

---

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

_{Reviews (1): Last reviewed commit: "Merge remote-tracking branch 'origin/fea..." | Re-trigger Greptile}

[posthog]

🦔 ReviewHog reviewed this pull request

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

Published 2 findings (view the review).

[posthog]

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

[posthog]

ReviewHog Report

Changes

Issues: 1 issue

Files (7)

• .changeset/canvas-masking-web.md
• .changeset/mask-widget-web-canvas.md
• example/lib/masking_tests_screen.dart
• posthog_flutter/lib/src/replay/mask/canvas_mask_registration_io.dart
• posthog_flutter/lib/src/replay/mask/canvas_mask_registration_web.dart
• posthog_flutter/lib/src/replay/mask/posthog_mask_widget.dart
• posthog_flutter/lib/src/replay/web/web_canvas_mask_provider.dart

Other findings (outside the changed lines)

Valid issues on this PR's files that sit on lines GitHub won't let us comment on inline.

Retry loop never backs off when _apply() keeps throwing, unlike the posthog-not-ready path

Priority: consider | File: posthog_flutter/lib/src/replay/web/web_canvas_mask_provider.dart:161-178 | Category: performance

Why we think it's a valid issue

• Checked: Traced _scheduleRetry (L164-181) and every _apply() throw source (set_config L248, stopSessionRecording/startSessionRecording L255-256), plus the paths that enter the chain with an exception in flight (_onMaskWidgetMounted catch L140-141, register catch L120-121).
• Found: The code claim is accurate: next is seeded to delay (L166) and only ramped inside the try on a posthogNotReady result (L172-175); a thrown _apply() skips to catch (L176-178) leaving next == delay, so _scheduleRetry(next) (L179) reschedules at the same interval. The posthogNotReady path deliberately backs off to a 4s ceiling (comment L161-163: 'polls forever once backed off to 4s'); the exception path does not.
• Found (reachability): A true infinite fixed-250ms loop requires set_config or stopSessionRecording to throw on every tick — if only startSessionRecording throws, the next tick sees sessionRecordingStarted()==false (L254), skips the restart, sets _applied=true (L260), and the chain terminates in ~2 ticks.
• Impact: Confirmed but bounded: under a persistent set_config/stopSessionRecording throw the chain re-runs the apply at 4Hz for the page's life, producing printIfDebug spam (L177) and wasted interop calls; recording is left running in both loop cases (no crash/hang/data-loss), and it only bites in an already-degenerate posthog-js state.
• Priority: Real, verified inconsistency with a one-line fix, but a rare/degenerate trigger and bounded (log-spam / wasted-cycles) impact — real-but-minor, so down-ranked from should_fix to consider rather than surfaced at higher urgency.

Issue description

This chunk adds a new, expected way to enter the shared _scheduleRetry chain with a genuine exception in flight: _onMaskWidgetMounted()'s catch block explicitly schedules a retry (_polling = true; _scheduleRetry(const Duration(milliseconds: 250));) when _apply() throws mid-way (e.g. set_config or stopSessionRecording/startSessionRecording failing). But _scheduleRetry's Timer callback only advances the backoff delay on the success/not-ready branch: next is initialized to the current delay and is only reassigned to doubled/capped-at-4s inside the try block, right before the early return. When _apply() throws again on that retry tick, execution jumps straight to catch (e) { printIfDebug(...); }, next is never touched, and _scheduleRetry(next) reschedules at the exact same delay it started with. Contrast this with the posthogNotReady path, which the adjacent comment explicitly says 'polls forever once backed off to 4s' to avoid hammering anything while waiting for a slow app boot — that reasoning was never extended to the exception path this PR newly makes reachable. If an app hits a persistent failure after a PostHogMaskWidget mounts (e.g. stopSessionRecording()/startSessionRecording() throwing every time due to a broken posthog-js state, a hostile monkey-patch, or a CSP/extension interference that's not transient), the SDK will retry the full _apply() — including set_config and a stopSessionRecording/startSessionRecording pair — every 250ms for the rest of the page session, since nothing ever raises the delay past its starting value. None of the existing tests ('an exception during one retry tick does not kill the chain' and 'retries the full apply when the restart throws on first register') exercise a repeated/persistent throw — both stub the failure to occur exactly once and succeed on the second attempt, so this fixed-interval-forever behavior has no test coverage and was not caught by any prior pass.

Suggested fix

Compute the backed-off next delay unconditionally (before or independent of the try/catch), so a repeated exception still ramps the interval up toward the same 4s ceiling used for the not-ready case, e.g. move the doubled/next calculation above the try, or wrap only the _apply() call itself in the try and always fall through to the backoff computation afterward.

[turnipdabeets]

valid — the "retry loop never backs off when _apply() keeps throwing" finding was correct (confirmed the exception path reused the incoming delay while the posthog-not-ready path ramped to 4s, and the same structure existed on the base branch #499). Fixed in 017c8a1: the backoff now computes up front so both paths follow the same 250ms→4s curve, with a regression test discriminating the doubling chain from fixed-rate retries by attempt count. Nice catch on the reachability analysis too — it correctly bounded the impact to log spam rather than data loss.

[marandaneto]

left a last comment, approving to unblock

[posthog]

ReviewHog Report

Changes

Issues: 2 issues

Files (7)

• .changeset/canvas-masking-web.md
• .changeset/mask-widget-web-canvas.md
• example/lib/masking_tests_screen.dart
• posthog_flutter/lib/src/replay/mask/canvas_mask_registration_io.dart
• posthog_flutter/lib/src/replay/mask/canvas_mask_registration_web.dart
• posthog_flutter/lib/src/replay/mask/posthog_mask_widget.dart
• posthog_flutter/lib/src/replay/web/web_canvas_mask_provider.dart