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

.changeset/canvas-masking-web.md

@@ -2,4 +2,4 @@
 "posthog_flutter": minor
 ---
 
-Add session replay canvas masking on Flutter web: `maskAllTexts`, `maskAllImages`, `PostHogMaskWidget`, and obscured text fields now apply to the CanvasKit canvas (requires posthog-js 1.408.0+; enable by declaring `session_recording.canvasCapture.maskRegionsFn` in `posthog.init`)
+Add session replay canvas masking on Flutter web: `maskAllTexts`, `maskAllImages`, `PostHogMaskWidget`, and obscured text fields now apply to the CanvasKit canvas — enable by declaring `session_recording.canvasCapture.maskRegionsFn` in `posthog.init`, or just by mounting a `PostHogMaskWidget` (requires posthog-js 1.408.0+)

example/lib/masking_tests_screen.dart

@@ -256,7 +256,7 @@ class _MaskingTestsScreenState extends State<MaskingTestsScreen> {
               // The amber box matches no masking rule on its own, so it is
               // covered only if the wrapper contributes its own rect.
               _buildTestSection(
-                'Test 15: PostHogMaskWidget with multiple children (needs maskAllTexts or maskAllImages)',
+                'Test 15: PostHogMaskWidget with multiple children',
                 PostHogMaskWidget(
                   child: Row(
                     mainAxisAlignment: MainAxisAlignment.spaceBetween,

posthog_flutter/lib/src/replay/mask/canvas_mask_registration_io.dart

@@ -0,0 +1,7 @@
+import 'package:flutter/widgets.dart';
+
+/// Canvas masking is a Flutter web concern; on every other platform
+/// `PostHogMaskWidget` is honored by the native screenshot pipeline instead.
+void notifyMaskWidgetMounted(BuildContext context) {}
+
+void notifyMaskWidgetUnmounted(BuildContext context) {}

posthog_flutter/lib/src/replay/mask/canvas_mask_registration_web.dart

@@ -0,0 +1,80 @@
+import 'package:flutter/scheduler.dart';
+import 'package:flutter/widgets.dart';
+
+import '../../util/logging.dart';
+import '../web/web_canvas_mask_provider.dart';
+import 'posthog_mask_controller.dart';
+
+/// A mounted `PostHogMaskWidget` is an explicit request for masking, so it
+/// opts the app into canvas masking even when `posthog.init` never declared
+/// `maskRegionsFn`.
+///
+/// Deferred to the end of the frame because `initState` runs during Flutter's
+/// build phase: registering calls straight into posthog-js and restarts an
+/// in-flight recording.
+void notifyMaskWidgetMounted(BuildContext context) {
+  WebCanvasMaskProvider.registerMaskWidgetContext(context);
+  SchedulerBinding.instance.addPostFrameCallback((_) {
+    try {
+      if (!_isInTrackedTree(context)) {
+        printIfDebug(
+          'PostHog: this PostHogMaskWidget is outside the PostHogWidget tree '
+          'PostHog tracks, so masking could never cover it — it does not '
+          'enable web canvas masking.',
+        );
+        return;
+      }
+      WebCanvasMaskProvider.notifyMaskWidgetMounted();
+    } catch (e) {
+      printIfDebug('PostHog: error enabling web canvas masking: $e');
+    }
+  });
+}
+
+void notifyMaskWidgetUnmounted(BuildContext context) {
+  WebCanvasMaskProvider.unregisterMaskWidgetContext(context);
+}
+
+/// The masking walk only sees the tracked tree (whose route-dependent root is
+/// [WebCanvasMaskProvider.trackedTreeRoot], the boundary this check walks
+/// against), so a mask widget outside it would opt masking in while its own
+/// rects are never produced — the walk would succeed and ship rects that do
+/// not cover the widget. With
+/// no tracked tree at all the opt-in stays allowed: every walk then fails and
+/// frames are skipped (fail closed), which is the documented behavior for an
+/// app missing PostHogWidget.
+///
+/// The check runs once, in the mount's post-frame callback: a null tracked
+/// context at that moment is treated as the no-PostHogWidget shape and
+/// allowed. That one-shot allowance is backstopped by
+/// [WebCanvasMaskProvider], which revalidates every mounted mask widget when
+/// regions are computed — if a PostHogWidget later mounts without containing
+/// this widget, frames are skipped (fail closed) rather than recorded
+/// unmasked.
+bool _isInTrackedTree(BuildContext context) {
+  final trackedContext =
+      PostHogMaskController.instance.containerKey.currentContext;
+  if (trackedContext == null) {
+    return true;
+  }
+  final tracked = WebCanvasMaskProvider.trackedTreeRoot(trackedContext);
+  if (tracked == null) {
+    // cannot prove the mask widget is outside the tracked tree
+    return true;
+  }
+  if (!context.mounted) {
+    return false;
+  }
+  final renderObject = context.findRenderObject();
+  if (renderObject == null) {
+    return false;
+  }
+  RenderObject? node = renderObject;
+  while (node != null) {
+    if (identical(node, tracked)) {
+      return true;
+    }
+    node = node.parent;
+  }
+  return false;
+}

posthog_flutter/lib/src/replay/mask/posthog_mask_widget.dart

@@ -1,14 +1,27 @@
 import 'package:flutter/material.dart';
 
+import 'canvas_mask_registration_io.dart'
+    if (dart.library.js_interop) 'canvas_mask_registration_web.dart';
+
 /// Masks a widget subtree in PostHog session replay snapshots.
 ///
 /// Wrap sensitive UI with [PostHogMaskWidget] to hide that area in captured
 /// screenshots, regardless of the global session replay masking settings.
 ///
-/// **Flutter web:** this has no effect unless canvas masking is enabled, since
-/// the canvas is masked by posthog-js rather than by this plugin. Declare
+/// **Flutter web:** the canvas is masked by posthog-js rather than by this
+/// plugin, so the first [PostHogMaskWidget] to mount turns canvas masking on —
+/// which restarts an in-flight recording once, because masking also excludes
+/// the Flutter semantics DOM tree via `blockSelector`, and posthog-js only
+/// reads that when recording starts. Frames captured before that first
+/// mount are recorded unmasked; to cover the window between `posthog.init` and
+/// Flutter booting, declare
 /// `session_recording: { canvasCapture: { maskRegionsFn: () => null } }`
-/// in your `posthog.init` call to turn it on. iOS and Android need no setup.
+/// in your `posthog.init` call — until this plugin takes over, those frames are
+/// skipped instead of recorded. Your app must be wrapped in `PostHogWidget`,
+/// and every [PostHogMaskWidget] must sit inside it — otherwise canvas frames
+/// are skipped instead of recorded unmasked, until the mask widget is moved
+/// inside `PostHogWidget` or removed. iOS and Android need no setup either
+/// way.
 class PostHogMaskWidget extends StatefulWidget {
   /// The widget subtree to mask in session replay snapshots.
   final Widget child;
@@ -27,10 +40,12 @@ class PostHogMaskWidgetState extends State<PostHogMaskWidget> {
   @override
   void initState() {
     super.initState();
+    notifyMaskWidgetMounted(context);
   }
 
   @override
   void dispose() {
+    notifyMaskWidgetUnmounted(context);
     super.dispose();
   }