Consume capture-runtime 0.1.0 from Maven Central (#52)

* Depend on Maven Central capture-runtime for Flutter Android builds.

Local and published plugin builds resolve com.gettugboat.sdk:capture-runtime
instead of compiling platforms/android or stubbing native capture.

* Open a Flutter pin PR after capture-runtime reaches Maven Central.

Keep the plugin pin from racing unpublished AARs: CI rejects a newer pin than VERSION_NAME, and a post-publish job waits for repo1 before bumping Flutter.

Author: Chinmay-KB

.github/workflows/publish-android.yml

@@ -4,6 +4,8 @@
 # 1. On push to main, creates tag capture-runtime-v<version> when that version
 #    is not already on GitHub Packages (or Maven Central, once configured).
 # 2. On that tag (push or workflow_dispatch), publishes the AAR.
+# 3. After a tag publish, waits for Maven Central repo1 then opens a Flutter
+#    pin PR (chore/pin-capture-runtime-<version>) if the plugin still lags.
 #
 # GitHub Packages is the default hosted registry (GITHUB_TOKEN). Maven Central
 # is optional until namespace + secrets exist; see docs/releases/process.md.
@@ -182,3 +184,21 @@ jobs:
             exit 0
           fi
           ./gradlew :capture-runtime:publishAndReleaseToMavenCentral -Ptugboat.publishMavenCentral=true
+
+  pin_flutter:
+    if: startsWith(github.ref, 'refs/tags/capture-runtime-v')
+    needs: publish
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      pull-requests: write
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          token: ${{ secrets.GITHUB_TOKEN }}
+      - name: Open Flutter pin PR
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: bash tool/ci/open-flutter-runtime-pin-pr.sh

README.md

@@ -24,10 +24,10 @@ The Tugboat CLI is maintained separately.
 | `docs/` | Architecture, integration, privacy, performance, releases |
 | `tool/ci` | Host test, generate, and release-control scripts |
 
-Do not copy the C++ core into the published pub package. In this monorepo the
-Flutter plugin compiles Android and Apple runtimes from `platforms/` (and
-`core/`) when those trees resolve. Published pub consumers get a stub HostApi
-that reports unsupported native capture and keep the default Flutter backend.
+Do not copy the C++ core into the published pub package. The Flutter Android
+plugin depends on Maven Central `com.gettugboat.sdk:capture-runtime`. Apple
+native capture still compiles `platforms/apple` sources in the monorepo;
+published pub checkouts without that tree stub iOS native capture.
 
 ## Capture backends
 
@@ -63,10 +63,10 @@ bash tool/ci/build-android-runtime.sh
 bash tool/ci/run-flutter-tests.sh
 ```
 
-Native Android apps consume the AAR from untracked `.local-maven/` after
-`bash tool/ci/build-android-runtime.sh`, or from GitHub Packages after a
-`capture-runtime-v*` tag. The Flutter plugin compiles
-`platforms/android/capture-runtime` from source in the monorepo.
+Native Android apps consume the AAR from Maven Central
+(`com.gettugboat.sdk:capture-runtime:0.1.0`), or from untracked `.local-maven/`
+after `bash tool/ci/build-android-runtime.sh`. The Flutter plugin uses the
+Maven Central coordinate and does not compile `platforms/android` from source.
 
 ## Development
 

docs/README.md

@@ -58,10 +58,10 @@ gates, canaries) are not listed below.
 
 ## Current compatibility
 
-- package version: `0.8.13` (`0.8.x` patch after published `0.8.12`);
-- native runtime: `capture-runtime` `0.1.0` (GitHub Packages on
-  `capture-runtime-v*`; Flutter still compiles from monorepo sources);
-- planned first native-capable adapter: Flutter `0.9.0` after privacy and performance gates;
+- package version: `0.8.14` (`0.8.x` patch; Android plugin uses Maven Central
+  `capture-runtime` `0.1.0`);
+- native runtime: `capture-runtime` `0.1.0` on Maven Central;
+- planned first native-default adapter: Flutter `0.9.0` after privacy and performance gates;
 - session JSON schema: `10`;
 - fingerprint schema: `6`;
 - minimum Dart SDK: `3.9.2`;

docs/architecture/repository-map.md

@@ -19,12 +19,12 @@ package references sources under `platforms/apple` and
 `core/image-processing`.
 
 Do not copy the C++ core into the published pub package. Files above a
-published pub archive are not part of that archive. In this monorepo the
-Flutter plugin compiles Android and Apple runtime sources when those trees
-resolve. Published pub archives omit those trees and stub native capture as
-unsupported. Native Android apps consume the local Maven AAR or the hosted
-GitHub Packages / Maven Central coordinate; native Apple apps still use the
-root CocoaPod / SwiftPM package.
+published pub archive are not part of that archive. The Flutter Android
+plugin depends on Maven Central `com.gettugboat.sdk:capture-runtime`. The
+iOS plugin compiles Apple runtime sources when `platforms/apple` resolves;
+published pub archives omit that tree and stub iOS native capture.
+Native Android apps consume Maven Central or the local Maven AAR; native
+Apple apps still use the root CocoaPod / SwiftPM package.
 
 Ownership rules: [repository-scope.md](repository-scope.md).
 Build commands: [common-build.md](../integration/common-build.md).

docs/architecture/repository-scope.md

@@ -62,6 +62,7 @@ In scope:
 - Return only masked JPEG bytes and bounded metadata
 - Local Maven publication for the native Android sample
 - Hosted GitHub Packages publication on `capture-runtime-v*` tags
+- Maven Central `com.gettugboat.sdk:capture-runtime` for Flutter and native apps
 
 Capture scale stays Dart-owned. The adapter sends the bitmap width and
 height that the current capturer would have used. The runtime serializes
@@ -85,9 +86,10 @@ older OS versions report `unsupportedApi` and Flutter falls back.
 
 ## Flutter adapter scope
 
-`package:tugboat` stays the public Dart API. First native-capable version is
-planned as `0.9.0`. This Phase 0/1 line is `0.8.13` and does not enable
-native capture.
+`package:tugboat` stays the public Dart API. Native Android capture is
+available as an opt-in on `0.8.14` via Maven Central `capture-runtime`
+`0.1.0`. This line does not enable native capture by default; `0.9.0` is
+still the planned native-default adapter.
 
 In scope for the Android and Apple CPU betas:
 
@@ -97,9 +99,9 @@ In scope for the Android and Apple CPU betas:
 - Send mask metadata and previous dHash; receive masked JPEG only
 - Automatic fallback; never publish native and Flutter results for one request
 - Preserve session schema, frame transport, scheduling, and mask policy
-- Android: the Flutter plugin compiles `capture-runtime` from source in the
-  monorepo. Native Android apps use the local Maven AAR or the hosted
-  GitHub Packages / Maven Central coordinate. iOS: the
+- Android: the Flutter plugin depends on Maven Central
+  `com.gettugboat.sdk:capture-runtime:0.1.0`. Native Android apps use the
+  same coordinate, or `.local-maven` for unpublished runtime work. iOS: the
   plugin compiles `TugboatCaptureRuntime` sources; the root CocoaPod remains
   for native Apple apps.
 

docs/integration/android-development.md

@@ -28,8 +28,8 @@ python3 tool/ci/dump-android-runtime-api.py > platforms/android/capture-runtime/
 Hosted publication (GitHub Packages, then Maven Central) is documented in
 [release process](../releases/process.md).
 
-The Flutter plugin at `sdks/flutter/packages/tugboat/android` compiles
-`CaptureRuntime` from this source tree (no unpublished Maven coordinate) and
-wraps it behind the Pigeon `NativeCaptureHostApi`. Published pub checkouts
-without `platforms/android` stub native capture as unsupported. Do not log
-pixel or JPEG data.
+The Flutter plugin at `sdks/flutter/packages/tugboat/android` depends on
+Maven Central `com.gettugboat.sdk:capture-runtime:0.1.0` and wraps it behind
+the Pigeon `NativeCaptureHostApi`. Changing `CaptureRuntime` for a Flutter
+build requires publishing a new AAR version and bumping that coordinate.
+Do not log pixel or JPEG data.

docs/integration/common-build.md

@@ -10,11 +10,10 @@ bash tool/ci/run-flutter-tests.sh
 bash tool/ci/verify-native-capture-pigeon.sh
 ```
 
-The Android AAR publishes to untracked `.local-maven/` for native Android
-apps and the sample. Hosted GitHub Packages / Maven Central publication is
-documented in [process.md](../releases/process.md). The Flutter plugin
-compiles `capture-runtime` from source when `platforms/android` is present,
-so example APKs do not need that Maven artifact.
+The Android AAR publishes to untracked `.local-maven/` for the standalone
+native sample. Hosted Maven Central publication is documented in
+[process.md](../releases/process.md). The Flutter plugin depends on
+`com.gettugboat.sdk:capture-runtime:0.1.0` from Maven Central.
 
 Release-control scripts (also run in CI):
 

docs/integration/flutter-development.md

@@ -20,10 +20,11 @@ outputs.
 
 Screenshot pixels still default to `RepaintBoundary`. Enable native CPU
 capture only through
-`TugboatScreenshotCaptureBackend.nativeCpuExperimental`. In the monorepo the
-Flutter plugin compiles the Android and Apple runtimes from source. It does
-not depend on unpublished Maven or CocoaPods artifacts. Published pub
-consumers get a stub that reports native capture unsupported. See
+`TugboatScreenshotCaptureBackend.nativeCpuExperimental`. In the monorepo and
+on pub.dev, the Android plugin depends on Maven Central
+`com.gettugboat.sdk:capture-runtime:0.1.0`. The iOS plugin still compiles
+`TugboatCaptureRuntime` from source when `platforms/apple` is present;
+published pub checkouts stub iOS native capture. See
 [native-cpu-experimental.md](native-cpu-experimental.md) and
 [apple-development.md](apple-development.md).
 

docs/releases/compatibility.md

@@ -2,17 +2,16 @@
 
 | Adapter | Adapter version | Native runtime |
 | --- | --- | --- |
+| Flutter `tugboat` | 0.8.14 | Android `com.gettugboat.sdk:capture-runtime:0.1.0` from Maven Central. Apple `TugboatCaptureRuntime` 0.1.x compiled from monorepo sources (unpublished CocoaPod is not required). Plugin iOS floor 12; native capture still reports unsupported below iOS 15. |
 | Flutter `tugboat` | 0.8.13 | Android `capture-runtime` 0.1.x compiled from monorepo sources (hosted Maven is not required). Apple `TugboatCaptureRuntime` 0.1.x compiled from monorepo sources (unpublished CocoaPod is not required). Plugin iOS floor 12; native capture still reports unsupported below iOS 15. |
 | Flutter `tugboat` | 0.8.12 | none (Flutter `flutterRepaintBoundary` only; session identity stamp patch) |
 | Flutter `tugboat` | 0.9.0 (planned) | Android `capture-runtime` 0.1.x and Apple `TugboatCaptureRuntime` 0.1.x |
 | Apple `TugboatCaptureRuntime` | 0.1.0 | unpublished local CocoaPod / SwiftPM; iOS 15 live Flutter-layer CPU path |
 | `@tugboat/react-native` | — | not started |
 
-The first tagged pair after gates pass will be Flutter `v0.9.0` with
-`capture-runtime-v0.1.0` on Maven Central. Until then native capture stays
-opt-in and the Flutter package remains on the 0.8.x line. Do not publish
-Apple `0.1.0`. GitHub Packages can host `capture-runtime` `0.1.0` for native
-Android apps before Central verification completes.
+Flutter `0.8.14` consumes `capture-runtime` `0.1.0` from Maven Central.
+Native capture stays opt-in. Do not publish Apple `0.1.0`. The first
+native-default adapter is still planned as Flutter `0.9.0`.
 
 CI requires this table to change whenever Flutter adapter source or the
 public Android/C ABI or Apple Swift surface changes

docs/releases/process.md

@@ -27,6 +27,9 @@ docs procedure.
 - Flutter adapter source (`lib/`, `android/`, `ios/`, `pigeons/`, `pubspec.yaml`)
   bumps `tugboat` and updates this compatibility table.
 - A runtime public API change that adapters consume also updates the table.
+- The Flutter plugin's `capture-runtime` Maven pin must not be newer than
+  `VERSION_NAME`. Changing the pin requires it to equal `VERSION_NAME`.
+  Runtime-only PRs may leave the pin lagging until Central has the new AAR.
 
 ## pub.dev (Flutter 0.8.x)
 
@@ -74,10 +77,26 @@ dependencies {
 }
 ```
 
-The Flutter plugin still compiles `platforms/android/capture-runtime` from
-source in the monorepo and stubs native capture in published pub archives.
-Do not point the plugin at GitHub Packages; pub.dev hosts cannot supply
-GitHub credentials.
+The Flutter plugin depends on Maven Central
+`com.gettugboat.sdk:capture-runtime:0.1.0`. Do not point it at GitHub
+Packages; pub.dev hosts cannot supply GitHub credentials. iOS native capture
+still compiles from monorepo sources and stubs in published pub archives.
+
+### Two-merge sequence for a new AAR
+
+1. Runtime PR: bump `VERSION_NAME` (for example `0.1.1`) and merge. Wait until
+   `publish-android.yml` has put that version on Maven Central (repo1 POM
+   returns 200).
+2. Flutter PR: pin
+   `implementation("com.gettugboat.sdk:capture-runtime:<that version>")`,
+   bump `tugboat` / `tugboat_dio`, and merge. That publishes to pub.dev.
+
+Do not merge a Flutter pin for a version that is not on repo1 yet. After a
+`capture-runtime-v*` tag publish, `publish-android.yml` waits for repo1 and
+opens `chore/pin-capture-runtime-<version>` when the plugin still lags. That
+job is a no-op if the pin already matches `VERSION_NAME` or the branch/PR
+already exists. Recovery: re-run **Publish Android runtime** on the tag.
+The repository must allow GitHub Actions to create pull requests.
 
 ### Maven Central (public hosts)
 
@@ -99,7 +118,8 @@ Required before the Flutter plugin can depend on the AAR from pub.dev.
 
 ## After native gates pass
 
-1. Confirm `capture-runtime` `0.1.0` is on Maven Central.
-2. Point the Flutter plugin at the published coordinate.
-3. Bump Flutter to `0.9.0`, keep native capture opt-in.
+1. Confirm `capture-runtime` `0.1.0` is on Maven Central (done for 0.8.14).
+2. Point the Flutter plugin at the published coordinate (done in 0.8.14).
+3. Bump Flutter to `0.9.0`, keep native capture opt-in until gates pass, then
+   consider making native capture the default.
 4. Tag `v0.9.0` (same pattern as 0.8.x) so GitHub Actions publishes the pub packages.