fix: Prevent drag updates from reaching removed components (#3901)

# Description

Fixes a crash caused by `MultiDragDispatcher` continuing to send drag
updates to components that were removed during an active drag.

Removed drag targets are now cancelled and cleaned up instead of
receiving further updates. This also keeps drag state consistent for
`DragCallbacks`.

Added regression tests for:
- joystick removal during active drag
- dragged component state cleanup after removal

## Checklist

- [x] I have followed the [Contributor Guide] when preparing my PR.
- [x] I have updated/added tests for ALL new/updated/fixed
functionality.
- [x] I have updated/added relevant documentation in `docs` and added
dartdoc comments with `///`.
- [ ] I have updated/added relevant examples in `examples` or `docs`.

## Breaking Change?

- [ ] Yes, this PR is a breaking change.
- [x] No, this PR is not a breaking change.

## Related Issues

Fixes #3897

Author: MikeChen1109

packages/flame/lib/src/events/flame_game_mixins/multi_drag_dispatcher.dart

@@ -84,21 +84,42 @@ class MultiDragDispatcher extends Component implements MultiDragListener {
   @mustCallSuper
   void onDragUpdate(DragUpdateEvent event) {
     final updated = <TaggedComponent<DragCallbacks>>{};
+    // Defer cleanup so stale targets can be cancelled after iteration.
+    final stale = <TaggedComponent<DragCallbacks>>{};
     event.deliverAtPoint(
       rootComponent: game,
       deliverToAll: true,
       eventHandler: (DragCallbacks component) {
         final record = TaggedComponent(event.pointerId, component);
         if (_records.contains(record)) {
-          component.onDragUpdate(event);
-          updated.add(record);
+          if (!component.isMounted || component.isRemoving) {
+            stale.add(record);
+          } else {
+            component.onDragUpdate(event);
+            updated.add(record);
+          }
         }
       },
     );
     for (final record in _records) {
-      if (record.pointerId == event.pointerId && !updated.contains(record)) {
-        record.component.onDragUpdate(event);
+      if (record.pointerId != event.pointerId) {
+        continue;
       }
+      final component = record.component;
+      if (!component.isMounted || component.isRemoving) {
+        stale.add(record);
+        continue;
+      }
+      if (!updated.contains(record)) {
+        component.onDragUpdate(event);
+      }
+    }
+    if (stale.isNotEmpty) {
+      final cancelEvent = DragCancelEvent(event.pointerId);
+      for (final record in stale) {
+        record.component.onDragCancel(cancelEvent);
+      }
+      _records.removeAll(stale);
     }
   }
 

packages/flame/test/components/joystick_component_test.dart

@@ -119,5 +119,43 @@ void main() {
         expect(joystick.knob!.position, closeToVector(Vector2(20, 10)));
       },
     );
+
+    testWithFlameGame(
+      'does not throw when joystick is removed '
+      'during an active drag and receives update',
+      (game) async {
+        final joystick = JoystickComponent(
+          knob: CircleComponent(radius: 5.0),
+          size: 20,
+          margin: const EdgeInsets.only(left: 20, top: 20),
+        );
+        await game.add(joystick);
+        await game.ready();
+        final dragDispatcher = game.firstChild<MultiDragDispatcher>()!;
+
+        dragDispatcher.handleDragStart(
+          1,
+          DragStartDetails(
+            localPosition: const Offset(20, 20),
+            globalPosition: const Offset(20, 20),
+          ),
+        );
+
+        game.remove(joystick);
+        await game.ready();
+
+        expect(
+          () => dragDispatcher.handleDragUpdate(
+            1,
+            DragUpdateDetails(
+              localPosition: const Offset(21, 20),
+              globalPosition: const Offset(21, 20),
+              delta: const Offset(1, 0),
+            ),
+          ),
+          returnsNormally,
+        );
+      },
+    );
   });
 }

packages/flame/test/events/component_mixins/drag_callbacks_test.dart

@@ -71,6 +71,47 @@ void main() {
       expect(component.dragEndEvent, equals(1));
     });
 
+    testWithFlameGame(
+      'removed dragged component receives cancel on update and clears state',
+      (game) async {
+        final component = _DragCallbacksComponent()
+          ..x = 10
+          ..y = 10
+          ..width = 10
+          ..height = 10;
+        await game.ensureAdd(component);
+        final dispatcher = game.firstChild<MultiDragDispatcher>()!;
+
+        dispatcher.onDragStart(
+          createDragStartEvents(
+            game: game,
+            localPosition: const Offset(12, 12),
+            globalPosition: const Offset(12, 12),
+          ),
+        );
+        expect(component.isDragged, isTrue);
+
+        game.remove(component);
+        await game.ready();
+
+        dispatcher.onDragUpdate(
+          createDragUpdateEvents(
+            game: game,
+            localPosition: const Offset(15, 15),
+            globalPosition: const Offset(15, 15),
+          ),
+        );
+
+        expect(component.dragCancelEvent, equals(1));
+        expect(component.dragEndEvent, equals(1));
+        expect(component.isDragged, isFalse);
+
+        dispatcher.onDragEnd(DragEndEvent(1, DragEndDetails()));
+        expect(component.dragCancelEvent, equals(1));
+        expect(component.dragEndEvent, equals(1));
+      },
+    );
+
     testWithFlameGame(
       'drag event update not called without onDragStart',
       (game) async {