Add Flutter plugin bridge and experimental native CPU capture

Convert package:tugboat into a Flutter plugin with a Pigeon host API.
Keep RepaintBoundary as the default pixel source and offer native CPU
capture as an opt-in backend that falls back without double-publishing.

Co-authored-by: Chinmay Kabi <chinmay@blend.to>

Author: cursoragent

.github/workflows/flutter-adapter.yml

@@ -0,0 +1,24 @@
+name: Flutter adapter
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened, ready_for_review]
+
+permissions:
+  contents: read
+
+jobs:
+  pigeon:
+    name: Verify Pigeon outputs
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Set up Flutter
+        uses: subosito/flutter-action@v2
+        with:
+          channel: stable
+      - name: Install Dart dependencies
+        run: flutter pub get
+      - name: Verify generated native capture bridges
+        run: bash tool/ci/verify-native-capture-pigeon.sh

.gitignore

@@ -10,7 +10,10 @@ build/
 .local-maven/
 platforms/android/local.properties
 **/.gradle/
+**/.gradle/**
+.cxx/
 **/.cxx/
+**/.cxx/**
 crash-*
 leak-*
 timeout-*

docs/README.md

@@ -10,6 +10,7 @@ should be verified in their own repositories.
 
 - [SDK README](../sdks/flutter/packages/tugboat/README.md) — install, public API, configuration, and limits
 - [Collector integration](integration/collector.md) — Flutter WebSocket and HTTP wire behavior
+- [Experimental native CPU capture](integration/native-cpu-experimental.md) — opt-in Android PixelCopy backend and fallback rules
 - [Production replay acceptance](integration/production-replay-acceptance.md) — release, Blend canary, and manual production replay gate
 - [Blend gesture check, 2026-08-26](integration/blend-gesture-check-2026-08-26.md) — local Android pinch/pan evidence and remaining recorder gaps
 - [Gesture PR review, 2026-08-27](integration/gesture-pr-review-2026-08-27.md) — Cursor review, follow-up fixes, tests, and device limits

docs/integration/native-cpu-experimental.md

@@ -0,0 +1,26 @@
+# Experimental native CPU screenshot capture
+
+Status: experimental opt-in, Android CPU path only
+
+`TugboatScreenshotCaptureBackend.flutterRepaintBoundary` remains the default.
+Set `screenshotCaptureBackend` to
+`TugboatScreenshotCaptureBackend.nativeCpuExperimental` only when you intend
+to exercise the native Android CPU backend.
+
+The native path:
+
+- Captures the Flutter engine `SurfaceView` with `PixelCopy`
+- Applies privacy masks and dHash in the portable C++ core
+- Encodes JPEG on the platform (quality 80)
+- Returns masked JPEG bytes and bounded metadata to Dart
+
+It automatically falls back to `RepaintBoundary` when the runtime is
+unsupported, the surface is unavailable, PixelCopy fails, processing fails, or
+the native timeout fires. Cancellation and disposal do not fall back. Native
+and Flutter results are never published for the same request.
+
+Raw pixels never cross the platform channel. Do not enable this backend in
+production until the privacy and performance gates in
+[cpu-capture-baseline.md](../performance/cpu-capture-baseline.md) pass.
+
+The Apple plugin currently reports native capture as unavailable.

docs/plans/2026-08-31-001-native-capture-cpu-plan.md

@@ -568,54 +568,54 @@ Use the Flutter backend on older supported devices.
 
 ### Phase 5 - Convert the Flutter SDK into a plugin
 
-- [ ] P5.01 Add Android plugin metadata to `tugboat`.
-- [ ] P5.02 Add Apple plugin metadata to `tugboat`.
-- [ ] P5.03 Add the Android plugin class.
-- [ ] P5.04 Add an Apple capability stub.
-- [ ] P5.05 Add Pigeon to the development toolchain.
-- [ ] P5.06 Define `getCapabilities`.
-- [ ] P5.07 Define `capture`.
-- [ ] P5.08 Define `dispose`.
-- [ ] P5.09 Generate the Dart bridge.
-- [ ] P5.10 Generate the Kotlin bridge.
-- [ ] P5.11 Generate the Swift bridge.
-- [ ] P5.12 Add generated-file verification to CI.
-- [ ] P5.13 Add `TugboatScreenshotCaptureBackend`.
-- [ ] P5.14 Add `flutterRepaintBoundary`.
-- [ ] P5.15 Add `nativeCpuExperimental`.
-- [ ] P5.16 Make `flutterRepaintBoundary` the default.
-- [ ] P5.17 Add `screenshotCaptureBackend` to replay configuration.
-- [ ] P5.18 Document the experimental status.
-- [ ] P5.19 Keep current capture-scale defaults.
-- [ ] P5.20 Keep JPEG quality 80.
-- [ ] P5.21 Keep the current dHash threshold.
-- [ ] P5.22 Keep the current frame transport schema.
-- [ ] P5.23 Add a capture backend interface.
-- [ ] P5.24 Move the current capturer behind that interface.
-- [ ] P5.25 Add the native CPU backend.
-- [ ] P5.26 Convert mask rectangles to normalized app coordinates.
-- [ ] P5.27 Send only mask metadata to native code.
-- [ ] P5.28 Send the previous dHash.
-- [ ] P5.29 Send the forced-capture flag.
-- [ ] P5.30 Receive only masked JPEG data.
-- [ ] P5.31 Convert native timings into capture diagnostics.
-- [ ] P5.32 Record the requested backend.
-- [ ] P5.33 Record the resolved backend.
-- [ ] P5.34 Record capture coverage.
-- [ ] P5.35 Record the fallback reason.
-- [ ] P5.36 Ignore stale native results.
-- [ ] P5.37 Prevent duplicate frame publication.
-- [ ] P5.38 Preserve current capture scheduling.
-- [ ] P5.39 Preserve current session semantics.
-- [ ] P5.40 Fall back when native capture is unsupported.
-- [ ] P5.41 Fall back when the render surface is unavailable.
-- [ ] P5.42 Fall back after a native timeout.
-- [ ] P5.43 Fall back after `PixelCopy` failure.
-- [ ] P5.44 Fall back after processing failure.
-- [ ] P5.45 Do not fall back after cancellation.
-- [ ] P5.46 Do not publish native and Flutter results together.
-- [ ] P5.47 Limit retries after a known native failure.
-- [ ] P5.48 Reset retry state after a lifecycle change.
+- [x] P5.01 Add Android plugin metadata to `tugboat`.
+- [x] P5.02 Add Apple plugin metadata to `tugboat`.
+- [x] P5.03 Add the Android plugin class.
+- [x] P5.04 Add an Apple capability stub.
+- [x] P5.05 Add Pigeon to the development toolchain.
+- [x] P5.06 Define `getCapabilities`.
+- [x] P5.07 Define `capture`.
+- [x] P5.08 Define `dispose`.
+- [x] P5.09 Generate the Dart bridge.
+- [x] P5.10 Generate the Kotlin bridge.
+- [x] P5.11 Generate the Swift bridge.
+- [x] P5.12 Add generated-file verification to CI.
+- [x] P5.13 Add `TugboatScreenshotCaptureBackend`.
+- [x] P5.14 Add `flutterRepaintBoundary`.
+- [x] P5.15 Add `nativeCpuExperimental`.
+- [x] P5.16 Make `flutterRepaintBoundary` the default.
+- [x] P5.17 Add `screenshotCaptureBackend` to replay configuration.
+- [x] P5.18 Document the experimental status.
+- [x] P5.19 Keep current capture-scale defaults.
+- [x] P5.20 Keep JPEG quality 80.
+- [x] P5.21 Keep the current dHash threshold.
+- [x] P5.22 Keep the current frame transport schema.
+- [x] P5.23 Add a capture backend interface.
+- [x] P5.24 Move the current capturer behind that interface.
+- [x] P5.25 Add the native CPU backend.
+- [x] P5.26 Convert mask rectangles to normalized app coordinates.
+- [x] P5.27 Send only mask metadata to native code.
+- [x] P5.28 Send the previous dHash.
+- [x] P5.29 Send the forced-capture flag.
+- [x] P5.30 Receive only masked JPEG data.
+- [x] P5.31 Convert native timings into capture diagnostics.
+- [x] P5.32 Record the requested backend.
+- [x] P5.33 Record the resolved backend.
+- [x] P5.34 Record capture coverage.
+- [x] P5.35 Record the fallback reason.
+- [x] P5.36 Ignore stale native results.
+- [x] P5.37 Prevent duplicate frame publication.
+- [x] P5.38 Preserve current capture scheduling.
+- [x] P5.39 Preserve current session semantics.
+- [x] P5.40 Fall back when native capture is unsupported.
+- [x] P5.41 Fall back when the render surface is unavailable.
+- [x] P5.42 Fall back after a native timeout.
+- [x] P5.43 Fall back after `PixelCopy` failure.
+- [x] P5.44 Fall back after processing failure.
+- [x] P5.45 Do not fall back after cancellation.
+- [x] P5.46 Do not publish native and Flutter results together.
+- [x] P5.47 Limit retries after a known native failure.
+- [x] P5.48 Reset retry state after a lifecycle change.
 
 ### Phase 6 - Validate privacy and correctness
 

pubspec.lock

@@ -73,14 +73,30 @@ packages:
       url: "https://pub.dev"
     source: hosted
     version: "2.1.2"
+  built_collection:
+    dependency: transitive
+    description:
+      name: built_collection
+      sha256: "376e3dd27b51ea877c28d525560790aee2e6fbb5f20e2f85d5081027d94e2100"
+      url: "https://pub.dev"
+    source: hosted
+    version: "5.1.1"
+  built_value:
+    dependency: transitive
+    description:
+      name: built_value
+      sha256: "31b24be6615ec7fcf70b3aa5a7469fe35826485e639a16dd7eb83ba30e4cc6a8"
+      url: "https://pub.dev"
+    source: hosted
+    version: "8.12.7"
   characters:
     dependency: transitive
     description:
       name: characters
-      sha256: f71061c654a3380576a52b451dd5532377954cf9dbd272a78fc8479606670803
+      sha256: faf38497bda5ead2a8c7615f4f7939df04333478bf32e4173fcb06d428b5716b
       url: "https://pub.dev"
     source: hosted
-    version: "1.4.0"
+    version: "1.4.1"
   charcode:
     dependency: transitive
     description:
@@ -121,6 +137,14 @@ packages:
       url: "https://pub.dev"
     source: hosted
     version: "1.1.2"
+  code_builder:
+    dependency: transitive
+    description:
+      name: code_builder
+      sha256: aa5932e94c6c39c2f9ec4e5e06dfdd11a9430a61f6c41b6ba75b28ce0c481baf
+      url: "https://pub.dev"
+    source: hosted
+    version: "4.12.0"
   collection:
     dependency: transitive
     description:
@@ -185,6 +209,14 @@ packages:
       url: "https://pub.dev"
     source: hosted
     version: "0.2.1"
+  dart_style:
+    dependency: transitive
+    description:
+      name: dart_style
+      sha256: "8a0e5fba27e8ee025d2ffb4ee820b4e6e2cf5e4246a6b1a477eb66866947e0bb"
+      url: "https://pub.dev"
+    source: hosted
+    version: "3.1.1"
   dbus:
     dependency: transitive
     description:
@@ -257,6 +289,14 @@ packages:
       url: "https://pub.dev"
     source: hosted
     version: "7.0.1"
+  fixnum:
+    dependency: transitive
+    description:
+      name: fixnum
+      sha256: b6dc7065e46c974bc7c5f143080a6764ec7a4be6da1285ececdc37be96de53be
+      url: "https://pub.dev"
+    source: hosted
+    version: "1.1.1"
   flutter:
     dependency: transitive
     description: flutter
@@ -372,18 +412,18 @@ packages:
     dependency: transitive
     description:
       name: matcher
-      sha256: dc58c723c3c24bf8d3e2d3ad3f2f9d7bd9cf43ec6feaa64181775e60190153f2
+      sha256: "31bd099b47c10cd1aeb55146a2d46ce0277630ecef3f7dae54ad7873f36696cd"
       url: "https://pub.dev"
     source: hosted
-    version: "0.12.17"
+    version: "0.12.20"
   material_color_utilities:
     dependency: transitive
     description:
       name: material_color_utilities
-      sha256: f7142bb1154231d7ea5f96bc7bde4bda2a0945d2806bb11670e30b850d56bdec
+      sha256: "9c337007e82b1889149c82ed242ed1cb24a66044e30979c44912381e9be4c48b"
       url: "https://pub.dev"
     source: hosted
-    version: "0.11.1"
+    version: "0.13.0"
   melos:
     dependency: "direct dev"
     description:
@@ -396,10 +436,10 @@ packages:
     dependency: transitive
     description:
       name: meta
-      sha256: e3641ec5d63ebf0d9b41bd43201a66e3fc79a65db5f61fc181f04cd27aab950c
+      sha256: "307249ce4ff29d58a18e97f6345f539382eb9c9c29ecda628900f31de0443dd9"
       url: "https://pub.dev"
     source: hosted
-    version: "1.16.0"
+    version: "1.19.0"
   mime:
     dependency: transitive
     description:
@@ -464,6 +504,14 @@ packages:
       url: "https://pub.dev"
     source: hosted
     version: "7.0.2"
+  pigeon:
+    dependency: transitive
+    description:
+      name: pigeon
+      sha256: fe36bc5ad43ab7f4d8a9d974850aef1148f6d88a53bd14b3d87475ec403a3cdb
+      url: "https://pub.dev"
+    source: hosted
+    version: "26.1.0"
   platform:
     dependency: transitive
     description:
@@ -585,10 +633,10 @@ packages:
     dependency: transitive
     description:
       name: test_api
-      sha256: "522f00f556e73044315fa4585ec3270f1808a4b186c936e612cab0b565ff1e00"
+      sha256: "2a122cbe059f8b610d3a5415f42e255b6c17b1f21eee1d960f31080237fb4f11"
       url: "https://pub.dev"
     source: hosted
-    version: "0.7.6"
+    version: "0.7.12"
   typed_data:
     dependency: transitive
     description:
@@ -609,10 +657,10 @@ packages:
     dependency: transitive
     description:
       name: vector_math
-      sha256: d530bd74fea330e6e364cda7a85019c434070188383e1cd8d9777ee586914c5b
+      sha256: f36f9f3be64c6198714492bb455c11056e33e2f85d9a0b676a48301e44fdcf47
       url: "https://pub.dev"
     source: hosted
-    version: "2.2.0"
+    version: "2.4.2"
   vm_service:
     dependency: transitive
     description:
@@ -678,5 +726,5 @@ packages:
     source: hosted
     version: "2.2.4"
 sdks:
-  dart: ">=3.9.2 <4.0.0"
+  dart: ">=3.11.0-0 <4.0.0"
   flutter: ">=3.35.0"

sdks/flutter/packages/tugboat/CHANGELOG.md

@@ -6,6 +6,10 @@ Patch release after `0.8.11`.
 
 - Record a regenerable JPEG size envelope for the current Dart encoder so the
   native CPU capture path can compare codec output against the same buffers.
+- Convert `tugboat` into a Flutter plugin with an experimental opt-in Android
+  native CPU capture backend (`nativeCpuExperimental`). The default remains
+  `flutterRepaintBoundary`, with automatic fallback when native capture is
+  unavailable or fails safely.
 
 ## 0.8.11