Emit overlay identity and presentation parent on route_change

packages/tugboat/CHANGELOG.md

@@ -1,3 +1,20 @@
+## 0.8.13
+
+Patch release after `0.8.12`.
+
+### Added
+
+- `route_change` now splits route identity (`routeName`, `routeType`,
+  `routeNamed`, and the matching `from*` fields) without changing `route`,
+  `fromRoute`, or `navigation`.
+- Overlay classification is the closed set `page | sheet | dialog | popup |
+  unknown`. Bottom sheets are `sheet` (no longer `modal`).
+- Overlay pushes include presentation parent (`presentedOver*`, `hostPage*`)
+  and a bounded same-navigator `routeStack` snapshot.
+- Claimed route changes copy `causeTargetFingerprint` and `causeGesture` from
+  the interaction. Overlay after-frames still capture under exploration
+  screenshot suppression when `overlayKind` is not `page`.
+
 ## 0.8.12
 
 Patch release after `0.8.11`.

packages/tugboat/README.md

@@ -5,10 +5,19 @@ 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.8.12`. Session JSON writers and readers use
+The current package version is `0.8.13`. Session JSON writers and readers use
 schema version `10` only. Structural fingerprints use fingerprint schema
 version `6`.
 
+## 0.8.13
+
+`route_change` now carries split route identity (`routeName` / `routeType` /
+`routeNamed`), a closed overlay kind (`page`, `sheet`, `dialog`, `popup`,
+`unknown`), presentation-parent fields for overlay pushes, and a bounded
+same-navigator `routeStack`. `fromRoute`, `route`, and `navigation` keep their
+existing meaning. Overlay after-frames still capture under exploration
+screenshot suppression.
+
 ## 0.8.12
 
 Session lifecycle POSTs now stamp the current runtime `userId` and traits on
@@ -241,9 +250,13 @@ installed.
 
 The supplied observer is intended to record standard Navigator `push`, `pop`,
 `replace`, and `remove` callbacks without application code calling the replay
-controller for each navigation. Dialog and modal-bottom-sheet routes can
-participate when they use that observed Navigator. Nested navigators need their
-own observer wiring, and native/system overlays are outside the Flutter
+controller for each navigation. Dialog, sheet, and other popup routes can
+participate when they use that observed Navigator. Unnamed sheets keep their
+runtime type as `route` and set `routeNamed: false`; the SDK does not invent a
+product name from the builder widget. Overlay pushes record the route
+immediately below (`presentedOver*`) and the nearest page (`hostPage*`) when
+the same-navigator stack can resolve them. Nested navigators need their own
+observer wiring, and native/system overlays are outside the Flutter
 Navigator/repaint-boundary contract.
 
 Each visible route change creates a route epoch and waits for the transition

packages/tugboat/lib/src/collector_mapper.dart

@@ -60,13 +60,7 @@ Map<String, Object?> mapTugboatEventToCollectorEvent({
       sessionId: sessionId,
       userId: userId,
       traitsId: traitsId,
-      extra: {
-        'routeChangeSchema': tugboatRouteChangeSchemaVersion,
-        if (data['fromRoute'] != null) 'fromRoute': data['fromRoute'],
-        if (data['route'] != null) 'route': data['route'],
-        if (data['navigation'] != null) 'navigation': data['navigation'],
-        if (data['causeEventId'] != null) 'causeEventId': data['causeEventId'],
-      },
+      extra: _routeChangeCollectorExtra(data),
     );
   }
 
@@ -204,3 +198,47 @@ int? frameNumberFromId(String frameId) {
   if (match == null) return null;
   return int.parse(match.group(1)!);
 }
+
+const _routeChangeCollectorKeys = <String>[
+  'fromRoute',
+  'route',
+  'navigation',
+  'causeEventId',
+  'causedByInteractionId',
+  'routeName',
+  'routeType',
+  'routeNamed',
+  'fromRouteName',
+  'fromRouteType',
+  'fromRouteNamed',
+  'overlayKind',
+  'presentedOverRoute',
+  'presentedOverRouteInstanceId',
+  'presentedOverOverlayKind',
+  'hostPageRoute',
+  'hostPageRouteInstanceId',
+  'routeStack',
+  'causeTargetFingerprint',
+  'causeGesture',
+];
+
+Map<String, Object?> _routeChangeCollectorExtra(Map<String, Object?> data) {
+  final extra = <String, Object?>{
+    'routeChangeSchema': tugboatRouteChangeSchemaVersion,
+  };
+  _copyPresentRouteChangeKeys(extra, data);
+  if (data['routeStackTruncated'] == true) {
+    extra['routeStackTruncated'] = true;
+  }
+  return extra;
+}
+
+void _copyPresentRouteChangeKeys(
+  Map<String, Object?> extra,
+  Map<String, Object?> data,
+) {
+  for (final key in _routeChangeCollectorKeys) {
+    final value = data[key];
+    if (value != null) extra[key] = value;
+  }
+}