Merge pull request #4 from blendto/fix/app-lifecycle-events

Fix/app lifecycle events

Author: Chinmay-KB

.github/workflows/version-bump-check.yml

@@ -0,0 +1,76 @@
+name: Version bump check
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened, ready_for_review]
+
+permissions:
+  contents: read
+
+jobs:
+  check-tugboat-version:
+    name: Require tugboat version bump
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Compare package version to base
+        env:
+          BASE_SHA: ${{ github.event.pull_request.base.sha }}
+          PACKAGE_PUBSPEC: packages/tugboat/pubspec.yaml
+        run: |
+          set -euo pipefail
+
+          extract_version() {
+            local file="$1"
+            if [[ ! -f "$file" ]]; then
+              echo ""
+              return
+            fi
+            grep -E '^version:' "$file" | head -1 | sed -E 's/^version:[[:space:]]*//' | tr -d '"' | tr -d "'" | tr -d '[:space:]'
+          }
+
+          if [[ ! -f "$PACKAGE_PUBSPEC" ]]; then
+            echo "::error::$PACKAGE_PUBSPEC is missing on this branch"
+            exit 1
+          fi
+
+          head_version="$(extract_version "$PACKAGE_PUBSPEC")"
+          if [[ -z "$head_version" ]]; then
+            echo "::error::Could not read version from $PACKAGE_PUBSPEC"
+            exit 1
+          fi
+
+          base_file="$(mktemp)"
+          if ! git show "${BASE_SHA}:${PACKAGE_PUBSPEC}" >"$base_file" 2>/dev/null; then
+            echo "Base branch has no $PACKAGE_PUBSPEC; treating as new package (ok)."
+            echo "PR version: $head_version"
+            exit 0
+          fi
+
+          base_version="$(extract_version "$base_file")"
+          rm -f "$base_file"
+
+          if [[ -z "$base_version" ]]; then
+            echo "::error::Could not read version from base $PACKAGE_PUBSPEC"
+            exit 1
+          fi
+
+          echo "Base version: $base_version"
+          echo "PR version:   $head_version"
+
+          if [[ "$head_version" == "$base_version" ]]; then
+            echo "::error::packages/tugboat version must be bumped before merge (still $base_version)."
+            exit 1
+          fi
+
+          higher="$(printf '%s\n%s\n' "$base_version" "$head_version" | sort -V | tail -n 1)"
+          if [[ "$higher" != "$head_version" ]]; then
+            echo "::error::PR version ($head_version) must be greater than base ($base_version)."
+            exit 1
+          fi
+
+          echo "Version bump detected: $base_version -> $head_version"

docs/README.md

@@ -27,8 +27,8 @@ verified in their own repositories.
 
 ## Current compatibility
 
-- package version: `0.2.0`;
-- session JSON schema: `6`;
+- package version: `0.4.0`;
+- session JSON schema: `7`;
 - fingerprint schema: `6`;
 - minimum Dart SDK: `3.9.2`;
 - minimum Flutter SDK: `3.35.0`.

packages/tugboat/README.md

@@ -5,7 +5,7 @@ checkpoints around meaningful interactions, compact structural anchors, route
 transitions, scrolling evidence, and optional viewport semantic maps. Capture
 can be sent to the local exploration WebSocket, the HTTP collector, or both.
 
-The current package version is `0.2.0`. Session JSON uses schema version `7`
+The current package version is `0.4.0`. Session JSON uses schema version `7`
 (readers still accept `6`), and structural fingerprints use fingerprint schema
 version `6`.
 

packages/tugboat/example/pubspec.yaml

@@ -32,7 +32,7 @@ resolution: workspace
 dependencies:
   flutter:
     sdk: flutter
-  tugboat: ^0.2.0
+  tugboat: ^0.4.0
 
   # The following adds the Cupertino Icons font to your application.
   # Use with the CupertinoIcons class for iOS style icons.

packages/tugboat/lib/src/controller.dart

@@ -1329,6 +1329,31 @@ class TugboatReplayController extends ChangeNotifier {
     });
   }
 
+  void recordAppLifecycleState(AppLifecycleState state) {
+    _addEvent(
+      TugboatEvent(
+        id: _nextId('event'),
+        atMs: atMs,
+        type: _appLifecycleEventType(state),
+        data: {'state': state.name},
+      ),
+    );
+  }
+
+  String _appLifecycleEventType(AppLifecycleState state) {
+    switch (state) {
+      case AppLifecycleState.paused:
+      case AppLifecycleState.hidden:
+        return 'app_backgrounded';
+      case AppLifecycleState.resumed:
+        return 'app_foregrounded';
+      case AppLifecycleState.inactive:
+        return 'app_inactive';
+      case AppLifecycleState.detached:
+        return 'app_detached';
+    }
+  }
+
   _RouteTransition _parseRouteTransition(String type, Route<dynamic>? route) {
     return _RouteTransition(
       kind: _RouteNavigationKind.parse(type),

packages/tugboat/lib/src/sdk_version.dart

@@ -1,3 +1,3 @@
 // Keep this in sync with packages/tugboat/pubspec.yaml. The SDK version test
 // reads pubspec.yaml directly so release bumps fail fast if this drifts.
-const tugboatSdkVersion = '0.2.0';
+const tugboatSdkVersion = '0.4.0';

packages/tugboat/lib/src/tugboat.dart

@@ -299,6 +299,9 @@ class _TugboatReplayRootState extends State<_TugboatReplayRoot>
 
   @override
   void didChangeAppLifecycleState(AppLifecycleState state) {
+    if (!TugboatReplay.disabled) {
+      TugboatReplay.controller?.recordAppLifecycleState(state);
+    }
     switch (state) {
       case AppLifecycleState.paused:
       case AppLifecycleState.hidden:

packages/tugboat/pubspec.yaml

@@ -1,7 +1,7 @@
 name: tugboat
 description: >-
   Screenshot-based session replay with compact interaction anchors for Tugboat.
-version: 0.3.0
+version: 0.4.0
 repository: https://github.com/blendto/tugboat-flutter
 issue_tracker: https://github.com/blendto/tugboat-flutter/issues
 homepage: https://github.com/blendto/tugboat-flutter

packages/tugboat/test/tugboat_replay_test.dart

@@ -94,6 +94,42 @@ void main() {
     await tester.pump();
   });
 
+  testWidgets('app background and foreground transitions are explicit', (
+    tester,
+  ) async {
+    await tester.pumpWidget(
+      MaterialApp(
+        builder: (context, child) =>
+            TugboatReplay.wrapApp(config: _testConfig, child: child!),
+        home: const SizedBox.expand(),
+      ),
+    );
+    await tester.pump();
+
+    final session = TugboatReplay.controller!.session!;
+    tester.binding.handleAppLifecycleStateChanged(AppLifecycleState.paused);
+    await tester.pump();
+    tester.binding.handleAppLifecycleStateChanged(AppLifecycleState.resumed);
+    await tester.pump();
+
+    final lifecycleEvents = session.events
+        .where(
+          (event) =>
+              event.type == 'app_backgrounded' ||
+              event.type == 'app_foregrounded',
+        )
+        .toList();
+    expect(lifecycleEvents.length, greaterThanOrEqualTo(2));
+    expect(
+      lifecycleEvents.map((event) => event.type),
+      containsAllInOrder(['app_backgrounded', 'app_foregrounded']),
+    );
+    expect(
+      lifecycleEvents.map((event) => event.data['state']),
+      containsAllInOrder(['paused', 'resumed']),
+    );
+  });
+
   testWidgets('captures initial screenshot and tap interaction anchors', (
     tester,
   ) async {