feat(replay): remove control value tracking

Author: Chinmay-KB

docs/README.md

@@ -28,8 +28,8 @@ verified in their own repositories.
 
 ## Current compatibility
 
-- package version: `0.4.17`;
-- session JSON schema: `8`;
+- package version: `0.5.0`;
+- session JSON schema: `9`;
 - fingerprint schema: `6`;
 - minimum Dart SDK: `3.9.2`;
 - minimum Flutter SDK: `3.35.0`.

docs/design/capture-and-fingerprint.md

@@ -63,7 +63,7 @@ current controller and keeps future calls to `wrapApp` inert. Runtime
 requiring a host rebuild. `deactivate()` tears capture down through the same
 gate. Pause/hidden flush pending delivery; detach ends the session once.
 
-Identity fields (session schema **v7**; readers accept v6):
+Identity fields (session schema **v9**; compatibility readers accept v6–v9):
 
 - `activationRequestId` — host request correlation
 - `captureSessionId` — SDK-emitted session (`session.id`)
@@ -76,7 +76,10 @@ emits exact build and fingerprint-schema provenance only.
 ## Session and event model
 
 The controller owns one bounded, in-memory `TugboatSession`. Serialized session
-JSON is schema version `7`. Readers accept schema versions `6` and `7`.
+JSON is schema version `9`. Compatibility readers accept schema versions
+`6` through `9`. Schema v9 does not write `controlValue`,
+`controlValueTransition`, or `semanticAnnotation` in event `data`;
+those fields are optional historic data in older sessions only.
 
 The session stores:
 
@@ -235,43 +238,9 @@ Developer-authored identity strings can still be emitted:
 - widget type names or configured `widgetNames` replacements;
 - canonical structural paths.
 
-Interaction events may also carry a `controlValue` payload (schema version 4) for
-valued controls (checkbox, switch, radio, slider, dropdown / menu item, chip)
-and for hit targets that expose Flutter semantic annotations:
-
-- bools and numbers are emitted literally;
-- enums and developer identifiers are emitted literally;
-- arbitrary strings, including numeric strings and single-word values, are
-  emitted literally;
-- explicit custom-control values can be supplied with
-  `TugboatControlValueScope`, including a stable `controlKey`, optional unit,
-  and numeric `min`, `max`, and `step` metadata.
-
-`tap` includes a `controlValue` snapshot sampled at pointer-down.
-`tap_settled` uses the distinct `controlValueTransition` contract with
-`before` / `after` snapshots. Its post-callback sample stays bound to the
-original hit element, so later taps, route changes, or dismissed overlays
-cannot donate unrelated control state. Slider drags that become `swipe` events
-carry a `controlValue` snapshot sampled at pointer-up.
-
-When a typed widget value is unavailable (custom GestureDetector rows, bottom
-sheets, etc.), the SDK still samples `SemanticsProperties` / live semantics
-nodes under the pointer and records raw `semanticValue` / `semanticLabel`.
-Standard controls may include both widget
-state and semantic annotations under `sources: ["semantics","widget"]`.
-
-Independently, every interaction event (`tap`, `tap_settled`, `swipe`,
-`scroll_start`, `scroll_end`) may carry a top-level `semanticAnnotation`
-payload (schema version 2) whenever Flutter semantics expose an identifier, label, value, or
-selection flag on the target. This covers ordinary buttons and scrollables as
-well as valued controls. The field is named `semanticAnnotation` to avoid
-colliding with `tap_settled.data.settleObservation.semantic` (state-signature
-change evidence).
-
 Bounds, pointer coordinates, scroll metrics, and masked screenshot pixels are
-also capture data. Apps must treat tags, route names, subview labels, and
-semantic value/label tokens as telemetry and avoid putting raw user PII in
-them.
+also capture data. Apps must treat tags, route names, and subview labels as
+telemetry and avoid putting user data in them.
 
 ## Screenshot pipeline
 

packages/tugboat/CHANGELOG.md

@@ -1,3 +1,28 @@
+## 0.5.0
+
+### Breaking changes
+
+- **Control-value and semantic-annotation telemetry** — session JSON writers
+  now emit schema version 9 and no longer write `controlValue`,
+  `controlValueTransition`, or `semanticAnnotation` in event `data`.
+  Readers that support historic schemas should continue to tolerate versions
+  6–8, where those fields may be present.
+- **Removed public barrel exports** —
+  `TugboatEncodedControlScalar`, `TugboatVisibleControlValue`,
+  `TugboatControlValueScope`, `TugboatControlValue`, and
+  `TugboatSemanticAnnotation`.
+- **Removed public schema constants** —
+  `tugboatControlValueSchemaVersion`,
+  `tugboatControlValueTransitionSchemaVersion`, and
+  `tugboatSemanticAnnotationSchemaVersion`.
+- **Removed public extraction and merge helpers** —
+  `tugboatControlValueForWidget`,
+  `tugboatControlValueFromSemanticsProperties`,
+  `tugboatControlValueFromSemanticsNode`,
+  `tugboatSemanticAnnotationFromProperties`,
+  `tugboatSemanticAnnotationFromNode`,
+  `tugboatMergeSemanticAnnotations`, and `tugboatMergeControlValues`.
+
 ## 0.4.18
 
 ### Fixed

packages/tugboat/README.md

@@ -5,9 +5,9 @@ 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.4.18`. Session JSON uses schema version `8`
-(readers still accept `6`), and structural fingerprints use fingerprint schema
-version `6`.
+The current package version is `0.5.0`. Session JSON writers emit schema
+version `9`; compatibility readers should accept versions `6` through
+`9`. Structural fingerprints use fingerprint schema version `6`.
 
 ## Install
 
@@ -19,6 +19,29 @@ import 'package:tugboat/tugboat.dart';
 
 The package requires Dart 3.9.2 or newer and Flutter 3.35.0 or newer.
 
+## Migrating to 0.5.0
+
+This is a breaking release. Session JSON written by 0.5.0 uses schema version
+`9` and no longer includes `controlValue`, `controlValueTransition`, or
+`semanticAnnotation` in event `data`. Consumers reading historical schemas
+`6`–`8` should treat those fields as optional historic data; new captures do
+not provide them.
+
+The public `package:tugboat/tugboat.dart` barrel no longer exports:
+
+- `TugboatEncodedControlScalar`, `TugboatVisibleControlValue`,
+  `TugboatControlValueScope`, `TugboatControlValue`, and
+  `TugboatSemanticAnnotation`;
+- `tugboatControlValueSchemaVersion`,
+  `tugboatControlValueTransitionSchemaVersion`, and
+  `tugboatSemanticAnnotationSchemaVersion`;
+- `tugboatControlValueForWidget`,
+  `tugboatControlValueFromSemanticsProperties`,
+  `tugboatControlValueFromSemanticsNode`,
+  `tugboatSemanticAnnotationFromProperties`,
+  `tugboatSemanticAnnotationFromNode`,
+  `tugboatMergeSemanticAnnotations`, and `tugboatMergeControlValues`.
+
 ## Minimal integration
 
 Install both the app wrapper and navigator observer. Capture is dormant by
@@ -209,11 +232,10 @@ Available mask levels are `explicitOnly`, `allTextAndMedia`, `allText`,
 stay visible; other custom-painted or decorated image surfaces are not
 classified by this mode, so wrap them in `TugboatSensitive` when needed).
 
-Control values and semantic strings are retained verbatim so session summaries
-and aggregate analysis can use values such as slider positions, video duration,
-and selected templates. Dynamic list discriminators remain hashed before they
-enter canonical paths. Telemetry also includes developer-authored routing and
-identity strings where applicable:
+The structural telemetry does not retain arbitrary `Text`, accessibility,
+tooltip, or icon label strings. Dynamic list discriminators are hashed before
+they enter canonical paths. Telemetry does include developer-authored routing
+and identity strings where applicable:
 
 - route names in `route_change.data` and anchor `routeKey` fields;
 - `TugboatSubView.label` in state/scroll context;
@@ -223,35 +245,10 @@ identity strings where applicable:
 - normalized bounds, pointer coordinates, scroll metrics, and screenshot
   pixels after the configured masking policy is applied.
 
-Screenshots and telemetry can contain rendered or semantic user content. Choose
-an explicit production masking policy and test custom widgets, platform views,
-overlays, and semantic labels before enabling production capture.
-
-### Explicit custom-control values
-
-Standard Flutter controls expose their typed state automatically. Wrap custom
-controls when the app knows a more useful stable key, unit, or range:
-
-```dart
-TugboatControlValueScope(
-  controlKey: 'video_duration',
-  role: 'slider',
-  unit: 'milliseconds',
-  min: 1_000,
-  max: 60_000,
-  step: 1_000,
-  value: TugboatVisibleControlValue.duration(
-    const Duration(seconds: 15),
-  ),
-  child: MyDurationSlider(),
-)
-```
-
-For template or preset selection, use a stable enum identifier:
-
-```dart
-value: TugboatVisibleControlValue.enumId('modern_minimal'),
-```
+Screenshots are the only captured surface that can contain rendered user
+content. Choose an explicit production masking policy and test custom widgets,
+platform views, and overlays in the target app before enabling production
+capture.
 
 ## Event and frame model
 

packages/tugboat/example/lib/screens/profile_screen.dart

@@ -16,7 +16,6 @@ class _ProfileScreenState extends State<ProfileScreen> {
   bool _darkMode = false;
   double _notificationVolume = 0.6;
   String _language = 'English';
-  int _generationCount = 1;
 
   @override
   Widget build(BuildContext context) {
@@ -144,28 +143,6 @@ class _ProfileScreenState extends State<ProfileScreen> {
               ),
             ],
           ),
-          DemoSection(
-            title: 'Generation settings',
-            children: [
-              Wrap(
-                spacing: 8,
-                children: [
-                  for (final count in [1, 2, 3, 4])
-                    Semantics(
-                      label: 'Number of generations',
-                      value: count.toString(),
-                      selected: _generationCount == count,
-                      child: FilledButton(
-                        key: Key('generation-count-$count'),
-                        onPressed: () =>
-                            setState(() => _generationCount = count),
-                        child: Text(count.toString()),
-                      ),
-                    ),
-                ],
-              ),
-            ],
-          ),
           DemoSection(
             title: 'Account actions',
             children: [

packages/tugboat/example/pubspec.yaml

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

packages/tugboat/example/test/widget_test.dart

@@ -1,23 +1,7 @@
-import 'package:flutter/material.dart';
-import 'package:flutter_test/flutter_test.dart';
-import 'package:tugboat/tugboat.dart';
 import 'package:tugboat_example/main.dart';
-
-Future<void> _waitForTugboatEvents(WidgetTester tester) async {
-  for (var attempt = 0; attempt < 12; attempt++) {
-    await tester.pump(const Duration(milliseconds: 50));
-  }
-}
-
-Map<String, Object?> _semanticAnnotation(TugboatEvent event) {
-  final raw = event.data['semanticAnnotation'];
-  return Map<String, Object?>.from(raw! as Map);
-}
+import 'package:flutter_test/flutter_test.dart';
 
 void main() {
-  setUp(TugboatReplay.resetForTest);
-  tearDown(TugboatReplay.resetForTest);
-
   testWidgets('demo app loads home screen', (tester) async {
     await tester.pumpWidget(const ReplayDemoApp());
     await tester.pump();
@@ -28,37 +12,4 @@ void main() {
       await tester.pump(const Duration(milliseconds: 300));
     }
   });
-
-  testWidgets(
-    'generation count tap emits its semantic parameter label and value',
-    (tester) async {
-      await tester.binding.setSurfaceSize(const Size(800, 1200));
-      addTearDown(() => tester.binding.setSurfaceSize(null));
-      TugboatReplay.activate(
-        activationRequestId: 'example-semantic-parameter-test',
-        profile: TugboatCaptureProfile.productionLean,
-      );
-      await tester.pumpWidget(const ReplayDemoApp());
-      await _waitForTugboatEvents(tester);
-
-      await tester.tap(find.text('Profile & settings'));
-      await tester.pumpAndSettle();
-      await _waitForTugboatEvents(tester);
-
-      await tester.tap(find.byKey(const Key('generation-count-3')));
-      await _waitForTugboatEvents(tester);
-
-      final tap = TugboatReplay.controller!.session!.events.lastWhere(
-        (event) => event.type == 'tap',
-      );
-      final annotation = _semanticAnnotation(tap);
-
-      expect(annotation['label'], {
-        'kind': 'string',
-        'value': 'Number of generations',
-      });
-      expect(annotation['value'], {'kind': 'string', 'value': '3'});
-      expect(annotation['selected'], isFalse);
-    },
-  );
 }