Merge PR #24: production semantic map policy

fix(replay): keep production semantic maps local

Author: Chinmay-KB

packages/tugboat/CHANGELOG.md

@@ -42,21 +42,14 @@
   instead of reusing the previous route's latest frame. Supersession,
   lifecycle cancellation, capture failure, and bounded timeout outcomes
   complete deterministically without allowing late readbacks to publish.
+- **Production viewport semantics stay local** — production sessions can still
+  build viewport semantic maps for tap resolution, but `viewport_semantic_map`
+  and `scroll_semantic_snapshot` events are emitted only during exploration so
+  UI text from semantic nodes is not uploaded in lean production captures.
 - **`ExplorationCaptureSink.recordFrame`** — forwards frame metadata and PNG bytes over the
   exploration WebSocket instead of dropping them. The CLI persists these under `frames/` when
   Flutter capture produces them (local capture may still be suppressed after the socket connects
   for performance; see `collector-integration.md`).
-
-### Removed
-
-- **`control_inventory` SDK events** — the SDK no longer emits per-screen control
-  inventories over the exploration WebSocket. Possible actions should be derived
-  from screenshots (for example via a VLM) instead of SDK-side widget-tree scans.
-  State anchors still include `actionableSummary` role counts for fingerprinting
-  only; that field is not a substitute for control discovery.
-
-### Changed
-
 - **`actionableSummary` deduplication** — count only leaf canonical controls (one per
   `FilledButton`/`TextButton`, not nested ink-well chrome). Fixes over-counting in modal,
   visibility, and rebuild fingerprint tests.
@@ -78,6 +71,14 @@
   `pushNamedAndRemoveUntil` still never bump the route epoch or cancel the pending
   destination capture (now covered by a dedicated regression test).
 
+### Removed
+
+- **`control_inventory` SDK events** — the SDK no longer emits per-screen control
+  inventories over the exploration WebSocket. Possible actions should be derived
+  from screenshots (for example via a VLM) instead of SDK-side widget-tree scans.
+  State anchors still include `actionableSummary` role counts for fingerprinting
+  only; that field is not a substitute for control discovery.
+
 ## 0.1.0
 
 - Initial Tugboat Flutter SDK with screenshot evidence, interaction anchors,

packages/tugboat/lib/src/controller.dart

@@ -3210,8 +3210,7 @@ class TugboatReplayController extends ChangeNotifier {
   }) {
     if (config.profile != TugboatCaptureProfile.exploration) return;
     // Always emit raw scene_inventory first (when new). Semantic-map emission
-    // must not replace or suppress inventory — it is the local inventory source
-    // of truth; maps are a companion / production bridge.
+    // must not replace or suppress inventory; maps are an exploration companion.
     final dedupeKey = '${inventory.stateSignature}|${inventory.inventoryHash}';
     if (_emittedInventories.add(dedupeKey)) {
       _addEvent(

packages/tugboat/lib/src/replay_config.dart

@@ -49,16 +49,19 @@ TugboatViewportSemanticPolicy resolveViewportSemanticPolicy({
     return TugboatViewportSemanticPolicy.off;
   }
 
-  final emitEvents =
-      mode == TugboatViewportSemanticMode.full ||
-      mode == TugboatViewportSemanticMode.fullWithDebugLogs;
-  final debugLogs = mode == TugboatViewportSemanticMode.fullWithDebugLogs;
   final exploration = profile == TugboatCaptureProfile.exploration;
   final production = profile == TugboatCaptureProfile.productionLean;
   if (!exploration && !production) {
     return TugboatViewportSemanticPolicy.off;
   }
 
+  final verboseMode =
+      mode == TugboatViewportSemanticMode.full ||
+      mode == TugboatViewportSemanticMode.fullWithDebugLogs;
+  final emitEvents = exploration && verboseMode;
+  final debugLogs =
+      exploration && mode == TugboatViewportSemanticMode.fullWithDebugLogs;
+
   return TugboatViewportSemanticPolicy(
     engineEnabled: true,
     emitEvents: emitEvents,

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.4.9';
+const tugboatSdkVersion = '0.4.10';

packages/tugboat/lib/src/viewport_semantic_mode.dart

@@ -6,9 +6,10 @@ enum TugboatViewportSemanticMode {
   /// Build maps on-device for tap verdicts only; do not emit map events.
   tapResolutionOnly,
 
-  /// Build and emit full semantic map / scroll snapshot events.
+  /// Build and emit full semantic map / scroll snapshot events in exploration.
+  /// Production uses this as tap-resolution-only to avoid uploading maps.
   full,
 
-  /// Same as [full], plus debugPrint diagnostics.
+  /// Same as [full], plus debugPrint diagnostics in exploration.
   fullWithDebugLogs,
 }

packages/tugboat/pubspec.yaml

@@ -1,7 +1,7 @@
 name: tugboat
 description: >-
   Screenshot-based session replay with compact interaction anchors for Tugboat.
-version: 0.4.9
+version: 0.4.10
 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/viewport_semantic_map_test.dart

@@ -391,48 +391,54 @@ void main() {
     expect(resolution.keys, isNot(contains('text')));
   });
 
-  testWidgets('production semantic map requires explicit test opt-in', (
-    tester,
-  ) async {
-    await tester.pumpWidget(
-      MaterialApp(
-        builder: (context, child) => TugboatReplay.wrapApp(
-          config: const TugboatReplayConfig(
-            profile: TugboatCaptureProfile.productionLean,
-            settleDelay: Duration.zero,
-            enableGlobalPointerCapture: false,
-            capturePixelRatio: 1.0,
-            viewportSemanticMode: TugboatViewportSemanticMode.full,
-            viewportSemanticMapMaxNodes: 1,
+  testWidgets(
+    'production semantic map emission stays off even with full mode',
+    (tester) async {
+      await tester.pumpWidget(
+        MaterialApp(
+          builder: (context, child) => TugboatReplay.wrapApp(
+            config: const TugboatReplayConfig(
+              profile: TugboatCaptureProfile.productionLean,
+              settleDelay: Duration.zero,
+              enableGlobalPointerCapture: false,
+              capturePixelRatio: 1.0,
+              viewportSemanticMode: TugboatViewportSemanticMode.full,
+              viewportSemanticMapMaxNodes: 1,
+            ),
+            child: child!,
           ),
-          child: child!,
-        ),
-        home: Scaffold(
-          body: Column(
-            children: [
-              FilledButton(onPressed: () {}, child: const Text('Go')),
-              FilledButton(onPressed: () {}, child: const Text('Next')),
-            ],
+          home: Scaffold(
+            body: Column(
+              children: [
+                FilledButton(onPressed: () {}, child: const Text('Go')),
+                FilledButton(onPressed: () {}, child: const Text('Next')),
+              ],
+            ),
           ),
         ),
-      ),
-    );
-    await tester.pump();
-    await _waitForCaptures(tester);
+      );
+      await tester.pump();
+      await _waitForCaptures(tester);
 
-    final controller = TugboatReplay.controller!;
-    controller.recordPointerDown(tester.getCenter(find.text('Go')));
-    await tester.pump();
+      final controller = TugboatReplay.controller!;
+      controller.recordPointerDown(tester.getCenter(find.text('Go')));
+      await tester.pump();
 
-    final mapEvent = controller.session!.events
-        .where((event) => event.type == 'viewport_semantic_map')
-        .single;
-    final nodes = mapEvent.data['nodes'] as List;
-    final summary = mapEvent.data['summary'] as Map<Object?, Object?>;
-    expect(nodes.length, lessThanOrEqualTo(1));
-    expect(summary['truncatedCount'], isA<int>());
-    expect(summary['totalNodes'], nodes.length);
-  });
+      final mapEvents = controller.session!.events
+          .where(
+            (event) =>
+                event.type == 'viewport_semantic_map' ||
+                event.type == 'scroll_semantic_snapshot',
+          )
+          .toList();
+      expect(mapEvents, isEmpty);
+
+      final tapEvent = controller.session!.events
+          .where((event) => event.type == 'tap')
+          .last;
+      expect(tapEvent.data['viewportSemanticResolution'], isNotNull);
+    },
+  );
 
   testWidgets('production semantic map stays off with default mode', (
     tester,
@@ -576,7 +582,10 @@ void main() {
           .whereType<String>()
           .where((fingerprint) => fingerprint.isNotEmpty)
           .toSet();
-      expect(linkedFingerprints.intersection(inventoryFingerprints), isNotEmpty);
+      expect(
+        linkedFingerprints.intersection(inventoryFingerprints),
+        isNotEmpty,
+      );
 
       final inventoryIndex = events.indexWhere(
         (event) => event.type == 'scene_inventory',

packages/tugboat/test/viewport_semantic_policy_test.dart

@@ -47,9 +47,19 @@ void main() {
       mode: TugboatViewportSemanticMode.full,
     );
     expect(productionFull.engineEnabled, isTrue);
-    expect(productionFull.emitEvents, isTrue);
+    expect(productionFull.emitEvents, isFalse);
+    expect(productionFull.debugLogs, isFalse);
     expect(productionFull.holdPersistentSemanticsHandle, isFalse);
 
+    final productionDebug = resolveViewportSemanticPolicy(
+      profile: TugboatCaptureProfile.productionLean,
+      mode: TugboatViewportSemanticMode.fullWithDebugLogs,
+    );
+    expect(productionDebug.engineEnabled, isTrue);
+    expect(productionDebug.emitEvents, isFalse);
+    expect(productionDebug.debugLogs, isFalse);
+    expect(productionDebug.holdPersistentSemanticsHandle, isFalse);
+
     final productionDefault = const TugboatReplayConfig(
       profile: TugboatCaptureProfile.productionLean,
     ).viewportSemanticPolicy;