feat(terminal): add opt-in OSC 52 clipboard writes (#16072)

* feat(terminal): add opt-in OSC 52 clipboard writes * Remove dup tr Signed-off-by: fufesou <linlong1266@gmail.com> --------- Signed-off-by: fufesou <linlong1266@gmail.com>
2026-09-08 21:41:02 +03:00 · 2026-09-05 13:21:49 +08:00
parent c1a587cfa4
commit 618bf37deb
68 changed files with 1279 additions and 119 deletions
--- a/flutter/lib/common/widgets/setting_widgets.dart
+++ b/flutter/lib/common/widgets/setting_widgets.dart
@@ -244,11 +244,38 @@ List<(String, String)> otherDefaultSettings() {
        kKeyUseAllMyDisplaysForTheRemoteSession
      ),
    ('Keep terminal sessions on disconnect', kOptionTerminalPersistent),
+    (
+      'Allow terminal apps to copy to clipboard',
+      kOptionAllowTerminalClipboardWrite
+    ),
  ];

  return v;
 }

+String getOtherDefaultSettingOption(String key) {
+  if (key == kOptionAllowTerminalClipboardWrite) {
+    return bind.mainGetLocalOption(key: key);
+  }
+  return bind.mainGetUserDefaultOption(key: key);
+}
+
+Future<void> setOtherDefaultSettingOption(String key, String value) {
+  if (key == kOptionAllowTerminalClipboardWrite) {
+    return bind.mainSetLocalOption(
+      key: key,
+      value: value == kTerminalClipboardWriteAllowed
+          ? kTerminalClipboardWriteAllowed
+          : kTerminalClipboardWriteDenied,
+    );
+  }
+  return bind.mainSetUserDefaultOption(key: key, value: value);
+}
+
+bool isOtherDefaultSettingReadOnly(String key) =>
+    isOptionFixed(key) ||
+    (key == kOptionAllowTerminalClipboardWrite && bind.isDisableSettings());
+
 class TrackpadSpeedWidget extends StatefulWidget {
  final SimpleWrapper<int> value;
  // If null, no debouncer will be applied.
--- a/flutter/lib/consts.dart
+++ b/flutter/lib/consts.dart
@@ -115,6 +115,11 @@ const String kOptionEnableAudio = "enable-audio";
 const String kOptionEnableCamera = "enable-camera";
 const String kOptionEnableTerminal = "enable-terminal";
 const String kOptionTerminalPersistent = "terminal-persistent";
+const String kOptionAllowTerminalClipboardWrite =
+    "allow-terminal-clipboard-write";
+const String kTerminalClipboardWriteUnconfigured = "";
+const String kTerminalClipboardWriteAllowed = "Y";
+const String kTerminalClipboardWriteDenied = "N";
 const String kOptionEnableTunnel = "enable-tunnel";
 const String kOptionEnableRemoteRestart = "enable-remote-restart";
 const String kOptionEnableBlockInput = "enable-block-input";
--- a/flutter/lib/desktop/pages/desktop_setting_page.dart
+++ b/flutter/lib/desktop/pages/desktop_setting_page.dart
@@ -2080,14 +2080,13 @@ class _DisplayState extends State<_Display> {
  }

  Widget otherRow(String label, String key) {
-    final value = bind.mainGetUserDefaultOption(key: key) == 'Y';
-    final isOptFixed = isOptionFixed(key);
+    final value = getOtherDefaultSettingOption(key) == 'Y';
+    final isOptFixed = isOtherDefaultSettingReadOnly(key);
    onChanged(bool b) async {
-      await bind.mainSetUserDefaultOption(
-          key: key,
-          value: b
-              ? 'Y'
-              : (key == kOptionEnableFileCopyPaste ? 'N' : defaultOptionNo));
+      await setOtherDefaultSettingOption(
+        key,
+        b ? 'Y' : (key == kOptionEnableFileCopyPaste ? 'N' : defaultOptionNo),
+      );
      setState(() {});
    }

--- a/flutter/lib/desktop/pages/terminal_page.dart
+++ b/flutter/lib/desktop/pages/terminal_page.dart
@@ -19,6 +19,8 @@ class TerminalPage extends StatefulWidget {
    required this.tabKey,
    this.forceRelay,
    this.connToken,
+    this.onClipboardWriteBlocked,
+    this.onClipboardWriteSucceeded,
  }) : super(key: key);
  final String id;
  final String? password;
@@ -26,6 +28,8 @@ class TerminalPage extends StatefulWidget {
  final bool? forceRelay;
  final bool? isSharedPassword;
  final String? connToken;
+  final ValueChanged<String>? onClipboardWriteBlocked;
+  final ValueChanged<String>? onClipboardWriteSucceeded;
  final int terminalId;

  /// Tab key for focus management, passed from parent to avoid duplicate construction
@@ -71,6 +75,8 @@ class _TerminalPageState extends State<TerminalPage>

    // Create terminal model with specific terminal ID
    _terminalModel = TerminalModel(_ffi, widget.terminalId);
+    _terminalModel.onClipboardWriteBlocked = widget.onClipboardWriteBlocked;
+    _terminalModel.onClipboardWriteSucceeded = widget.onClipboardWriteSucceeded;
    debugPrint(
        '[TerminalPage] Terminal model created for terminal ${widget.terminalId}');

--- a/flutter/lib/desktop/pages/terminal_tab_page.dart
+++ b/flutter/lib/desktop/pages/terminal_tab_page.dart
@@ -1,3 +1,4 @@
+import 'dart:async';
 import 'dart:convert';

 import 'package:desktop_multi_window/desktop_multi_window.dart';
@@ -10,6 +11,8 @@ import 'package:flutter_hbb/models/state_model.dart';
 import 'package:flutter_hbb/desktop/widgets/tabbar_widget.dart';
 import 'package:flutter_hbb/utils/multi_window_manager.dart';
 import 'package:flutter_hbb/models/model.dart';
+import 'package:flutter_hbb/models/terminal_copy_shortcut.dart';
+import 'package:flutter_hbb/models/terminal_model.dart';
 import 'package:get/get.dart';

 import '../../models/platform_model.dart';
@@ -19,6 +22,12 @@ import '../widgets/material_mod_popup_menu.dart' as mod_menu;
 import '../widgets/popup_menu.dart';
 import 'package:bot_toast/bot_toast.dart';

+typedef _TerminalClipboardSource = ({
+  String peerId,
+  int terminalId,
+  String tabKey,
+});
+
 class TerminalTabPage extends StatefulWidget {
  final Map<String, dynamic> params;

@@ -30,6 +39,18 @@ class TerminalTabPage extends StatefulWidget {

 class _TerminalTabPageState extends State<TerminalTabPage> {
  DesktopTabController get tabController => Get.find<DesktopTabController>();
+  bool get _canConfigureTerminalClipboardPermission =>
+      canConfigureTerminalClipboardPermission(
+        settingsDisabled: bind.isDisableSettings(),
+        optionFixed: isOptionFixed(kOptionAllowTerminalClipboardWrite),
+      );
+  bool get _canHandleTerminalClipboardWriteRequest =>
+      canHandleTerminalClipboardWriteRequest(
+        localOption: bind.mainGetLocalOption(
+          key: kOptionAllowTerminalClipboardWrite,
+        ),
+        canConfigurePermission: _canConfigureTerminalClipboardPermission,
+      );

  static const IconData selectedIcon = Icons.terminal;
  static const IconData unselectedIcon = Icons.terminal_outlined;
@@ -38,6 +59,9 @@ class _TerminalTabPageState extends State<TerminalTabPage> {
  final Set<String> _closingTabs = {};
  // When true, all session cleanup should persist (window-level close in progress)
  bool _windowClosing = false;
+  CancelFunc? _terminalClipboardNoticeCancel;
+  final _terminalClipboardNotice =
+      TerminalClipboardNoticeCoordinator<_TerminalClipboardSource>();

  _TerminalTabPageState(Map<String, dynamic> params) {
    Get.put(DesktopTabController(tabType: DesktopTabType.terminal));
@@ -45,7 +69,10 @@ class _TerminalTabPageState extends State<TerminalTabPage> {
      WindowController.fromWindowId(windowId())
          .setTitle(getWindowNameWithId(id));
    };
-    tabController.onRemoved = (_, id) => onRemoveId(id);
+    tabController.onRemoved = (_, id) {
+      _closeTerminalClipboardNoticeForTab(id);
+      onRemoveId(id);
+    };
    tabController.onCloseWindow = _closeWindowFromConnection;
    final terminalId = params['terminalId'] ?? _nextTerminalId++;
    tabController.add(_createTerminalTab(
@@ -70,6 +97,11 @@ class _TerminalTabPageState extends State<TerminalTabPage> {
    final alias = bind.mainGetPeerOptionSync(id: peerId, key: 'alias');
    final tabLabel =
        alias.isNotEmpty ? '$alias #$terminalId' : '$peerId #$terminalId';
+    final clipboardSource = (
+      peerId: peerId,
+      terminalId: terminalId,
+      tabKey: tabKey,
+    );
    return TabInfo(
      key: tabKey,
      label: tabLabel,
@@ -86,10 +118,169 @@ class _TerminalTabPageState extends State<TerminalTabPage> {
        tabController: tabController,
        forceRelay: forceRelay,
        connToken: connToken,
+        onClipboardWriteBlocked: _canHandleTerminalClipboardWriteRequest
+            ? (text) => _handleTerminalClipboardWriteBlocked(
+                  clipboardSource,
+                  text,
+                )
+            : null,
+        onClipboardWriteSucceeded: (_) {
+          _handleTerminalClipboardWriteSucceeded(clipboardSource);
+        },
      ),
    );
  }

+  void _handleTerminalClipboardWriteBlocked(
+    _TerminalClipboardSource source,
+    String clipboardText,
+  ) {
+    if (!mounted) return;
+    final option = bind.mainGetLocalOption(
+      key: kOptionAllowTerminalClipboardWrite,
+    );
+    final request = _terminalClipboardNotice.recordBlocked(
+      source: source,
+      text: clipboardText,
+      option: option,
+      canWrite: _canWriteTerminalClipboard,
+    );
+    if (request != null) _showTerminalClipboardNotice(request);
+  }
+
+  void _showTerminalClipboardNotice(
+    TerminalClipboardNoticeRequest<_TerminalClipboardSource> request,
+  ) {
+    _terminalClipboardNoticeCancel = BotToast.showCustomNotification(
+      duration: null,
+      enableSlideOff: false,
+      onlyOne: true,
+      onClose: _handleTerminalClipboardNoticeClosed,
+      toastBuilder: (_) => AnimatedBuilder(
+        animation: _terminalClipboardNotice,
+        builder: (_, __) => MaterialBanner(
+          leading: const Icon(Icons.content_copy_outlined),
+          content: Text(translate(kTerminalClipboardNoticeMessageKey)),
+          actions: [
+            TextButton(
+              onPressed: _terminalClipboardNotice.canClaimAction
+                  ? _handleTerminalClipboardNegativeAction
+                  : null,
+              child: Text(translate(request.negativeActionKey)),
+            ),
+            TextButton(
+              onPressed: _terminalClipboardNotice.canClaimAction
+                  ? _handleTerminalClipboardPositiveAction
+                  : null,
+              child: Text(translate(request.actionKey)),
+            ),
+          ],
+        ),
+      ),
+    );
+  }
+
+  void _handleTerminalClipboardNegativeAction() {
+    final request = _terminalClipboardNotice.claimCurrentAction();
+    if (request == null) return;
+    if (request.persistAllowed) {
+      unawaited(_declineTerminalClipboardWrite());
+    } else {
+      _closeTerminalClipboardNotice();
+    }
+  }
+
+  void _handleTerminalClipboardPositiveAction() {
+    final request = _terminalClipboardNotice.claimCurrentAction();
+    if (request == null) return;
+    unawaited(_completeTerminalClipboardWrite(request));
+  }
+
+  void _handleTerminalClipboardNoticeClosed() {
+    _terminalClipboardNoticeCancel = null;
+    _terminalClipboardNotice.noticeClosed();
+  }
+
+  bool _canWriteTerminalClipboard(
+    _TerminalClipboardSource source,
+  ) {
+    if (!_canHandleTerminalClipboardWriteRequest) return false;
+    final ffi = TerminalConnectionManager.getExistingConnection(source.peerId);
+    return ffi != null &&
+        !ffi.closed &&
+        ffi.ffiModel.permissions['clipboard'] != false &&
+        tabController.state.value.tabs.any((tab) => tab.key == source.tabKey) &&
+        ffi.terminalModels.containsKey(source.terminalId);
+  }
+
+  void _handleTerminalClipboardWriteSucceeded(
+    _TerminalClipboardSource source,
+  ) {
+    final request = _terminalClipboardNotice.currentForSource(source);
+    if (request == null) return;
+    _closeTerminalClipboardNotice();
+  }
+
+  Future<void> _declineTerminalClipboardWrite() async {
+    try {
+      await bind.mainSetLocalOption(
+        key: kOptionAllowTerminalClipboardWrite,
+        value: kTerminalClipboardWriteDenied,
+      );
+    } catch (error) {
+      debugPrint(
+          '[TerminalTabPage] Failed to save terminal clipboard permission: $error');
+      return;
+    } finally {
+      _terminalClipboardNotice.releaseAction();
+    }
+    _closeTerminalClipboardNotice();
+  }
+
+  Future<void> _completeTerminalClipboardWrite(
+    TerminalClipboardNoticeRequest<_TerminalClipboardSource> request,
+  ) async {
+    final source = request.source;
+    var completed = false;
+    try {
+      completed = await completeTerminalClipboardWrite(
+        clipboardText: request.text,
+        canWrite: () => _canWriteTerminalClipboard(source),
+        writeClipboard: writeTerminalClipboard,
+        persistAllowed: request.persistAllowed
+            ? () => bind.mainSetLocalOption(
+                  key: kOptionAllowTerminalClipboardWrite,
+                  value: kTerminalClipboardWriteAllowed,
+                )
+            : null,
+      );
+    } catch (error) {
+      debugPrint(
+          '[TerminalTabPage] Failed to complete terminal clipboard write: $error');
+    } finally {
+      _terminalClipboardNotice.releaseAction();
+    }
+    if (!completed) return;
+    _closeTerminalClipboardNotice();
+  }
+
+  void _closeTerminalClipboardNoticeForTab(String tabKey) {
+    final current = _terminalClipboardNotice.current;
+    if (current?.source.tabKey != tabKey) return;
+    _closeTerminalClipboardNotice();
+  }
+
+  void _closeTerminalClipboardNotice() {
+    if (!_terminalClipboardNotice.beginClose()) return;
+    final cancel = _terminalClipboardNoticeCancel;
+    if (cancel == null) {
+      debugPrint('[TerminalTabPage] Clipboard notice controller is missing');
+      _terminalClipboardNotice.noticeClosed();
+      return;
+    }
+    cancel();
+  }
+
  /// Unified tab close handler for all close paths (button, shortcut, programmatic).
  /// Shows audit dialog, cleans up session if not persistent, then removes the UI tab.
  Future<void> _closeTab(String tabKey) async {
@@ -147,6 +338,8 @@ class _TerminalTabPageState extends State<TerminalTabPage> {
    // Remove all UI tabs immediately (same instant behavior as the old tabController.clear())
    // Keep the cleanup target lookup below synchronous before its first await:
    // it relies on the current frame still retaining each TerminalPage's FFI/model.
+    _terminalClipboardNotice.clear();
+    _terminalClipboardNoticeCancel?.call();
    tabController.clear();
    // Run session cleanup in parallel with bounded timeout (closeTerminal() has internal 3s timeout).
    // Skip tabs already being closed by a concurrent _closeTab() to avoid duplicate FFI calls.
@@ -357,6 +550,8 @@ class _TerminalTabPageState extends State<TerminalTabPage> {
  @override
  void dispose() {
    HardwareKeyboard.instance.removeHandler(_handleKeyEvent);
+    _terminalClipboardNotice.clear();
+    _terminalClipboardNoticeCancel?.call();
    super.dispose();
  }

--- a/flutter/lib/mobile/pages/settings_page.dart
+++ b/flutter/lib/mobile/pages/settings_page.dart
@@ -1269,16 +1269,18 @@ class __DisplayPageState extends State<_DisplayPage> {
  }

  SettingsTile otherRow(String label, String key) {
-    final value = bind.mainGetUserDefaultOption(key: key) == 'Y';
-    final isOptFixed = isOptionFixed(key);
+    final value = getOtherDefaultSettingOption(key) == 'Y';
+    final isOptFixed = isOtherDefaultSettingReadOnly(key);
    return SettingsTile.switchTile(
      initialValue: value,
      title: Text(translate(label)),
      onToggle: isOptFixed
          ? null
          : (b) async {
-              await bind.mainSetUserDefaultOption(
-                  key: key, value: b ? 'Y' : defaultOptionNo);
+              await setOtherDefaultSettingOption(
+                key,
+                b ? 'Y' : defaultOptionNo,
+              );
              setState(() {});
            },
    );
--- a/flutter/lib/mobile/pages/terminal_page.dart
+++ b/flutter/lib/mobile/pages/terminal_page.dart
@@ -11,6 +11,7 @@ import 'package:flutter_hbb/models/model.dart';
 import 'package:flutter_hbb/models/platform_model.dart';
 import 'package:flutter_hbb/models/terminal_copy_shortcut.dart';
 import 'package:flutter_hbb/models/terminal_model.dart';
+import 'package:flutter_hbb/models/terminal_mouse_handler.dart';
 import 'package:flutter_hbb/mobile/terminal_keyboard_utils.dart';
 import 'package:flutter_hbb/web/dummy.dart'
    if (dart.library.html) 'package:flutter_hbb/web/terminal_font.dart';
@@ -19,6 +20,49 @@ import 'package:xterm/xterm.dart';
 import '../../desktop/pages/terminal_connection_manager.dart';
 import '../../consts.dart';

+const _terminalBackgroundOpacity = 0.7;
+
+Widget _buildTerminalViewForPlatform({
+  required bool reportMouseInput,
+  required bool reportTouchInput,
+  required Terminal terminal,
+  required TerminalController controller,
+  required TerminalStyle textStyle,
+  required EdgeInsets padding,
+  required bool deleteDetection,
+  required Map<ShortcutActivator, Intent>? shortcuts,
+  required FocusOnKeyEventCallback onKeyEvent,
+  required void Function(TapDownDetails, CellOffset) onSecondaryTapDown,
+}) {
+  if (reportMouseInput || reportTouchInput) {
+    return TerminalMouseInteraction(
+      terminal,
+      controller: controller,
+      autofocus: true,
+      textStyle: textStyle,
+      deleteDetection: deleteDetection,
+      reportTouchInput: reportTouchInput,
+      shortcuts: shortcuts,
+      onKeyEvent: onKeyEvent,
+      backgroundOpacity: _terminalBackgroundOpacity,
+      padding: padding,
+      onSecondaryTapDown: onSecondaryTapDown,
+    );
+  }
+  return TerminalView(
+    terminal,
+    controller: controller,
+    autofocus: true,
+    textStyle: textStyle,
+    deleteDetection: deleteDetection,
+    shortcuts: shortcuts,
+    onKeyEvent: onKeyEvent,
+    backgroundOpacity: _terminalBackgroundOpacity,
+    padding: padding,
+    onSecondaryTapDown: onSecondaryTapDown,
+  );
+}
+
 class TerminalPage extends StatefulWidget {
  const TerminalPage({
    Key? key,
@@ -41,6 +85,19 @@ class TerminalPage extends StatefulWidget {

 class _TerminalPageState extends State<TerminalPage>
    with AutomaticKeepAliveClientMixin, WidgetsBindingObserver {
+  bool get _canConfigureTerminalClipboardPermission =>
+      canConfigureTerminalClipboardPermission(
+        settingsDisabled: bind.isDisableSettings(),
+        optionFixed: isOptionFixed(kOptionAllowTerminalClipboardWrite),
+      );
+  bool get _canHandleTerminalClipboardWriteRequest =>
+      canHandleTerminalClipboardWriteRequest(
+        localOption: bind.mainGetLocalOption(
+          key: kOptionAllowTerminalClipboardWrite,
+        ),
+        canConfigurePermission: _canConfigureTerminalClipboardPermission,
+      );
+
  late FFI _ffi;
  late TerminalModel _terminalModel;
  double? _cellHeight;
@@ -57,6 +114,9 @@ class _TerminalPageState extends State<TerminalPage>
  // For iOS edge swipe gesture
  double _swipeStartX = 0;
  double _swipeCurrentX = 0;
+  ScaffoldFeatureController<MaterialBanner, MaterialBannerClosedReason>?
+      _terminalClipboardNoticeController;
+  final _terminalClipboardNotice = TerminalClipboardNoticeCoordinator<int>();

  // For web only.
  // 'monospace' does not work on web, use Google Fonts, `??` is only for null safety.
@@ -89,6 +149,12 @@ class _TerminalPageState extends State<TerminalPage>

    // Create terminal model with specific terminal ID
    _terminalModel = TerminalModel(_ffi, widget.terminalId);
+    if (_canHandleTerminalClipboardWriteRequest) {
+      _terminalModel.onClipboardWriteBlocked =
+          _handleTerminalClipboardWriteBlocked;
+      _terminalModel.onClipboardWriteSucceeded =
+          _handleTerminalClipboardWriteSucceeded;
+    }
    debugPrint(
        '[TerminalPage] Terminal model created for terminal ${widget.terminalId}');

@@ -134,12 +200,144 @@ class _TerminalPageState extends State<TerminalPage>
    _ffi.ffiModel.updateEventListener(_ffi.sessionId, widget.id);
  }

+  void _handleTerminalClipboardWriteBlocked(String clipboardText) {
+    if (!mounted) return;
+    final option = bind.mainGetLocalOption(
+      key: kOptionAllowTerminalClipboardWrite,
+    );
+    final request = _terminalClipboardNotice.recordBlocked(
+      source: widget.terminalId,
+      text: clipboardText,
+      option: option,
+      canWrite: (_) => _canWriteTerminalClipboard,
+    );
+    if (request != null) _showTerminalClipboardNotice(request);
+  }
+
+  void _showTerminalClipboardNotice(
+    TerminalClipboardNoticeRequest<int> request,
+  ) {
+    final controller = ScaffoldMessenger.of(context).showMaterialBanner(
+      MaterialBanner(
+        leading: const Icon(Icons.content_copy_outlined),
+        content: Text(translate(kTerminalClipboardNoticeMessageKey)),
+        actions: [
+          AnimatedBuilder(
+            animation: _terminalClipboardNotice,
+            builder: (_, __) => TextButton(
+              onPressed: _terminalClipboardNotice.canClaimAction
+                  ? _handleTerminalClipboardNegativeAction
+                  : null,
+              child: Text(translate(request.negativeActionKey)),
+            ),
+          ),
+          AnimatedBuilder(
+            animation: _terminalClipboardNotice,
+            builder: (_, __) => TextButton(
+              onPressed: _terminalClipboardNotice.canClaimAction
+                  ? _handleTerminalClipboardPositiveAction
+                  : null,
+              child: Text(translate(request.actionKey)),
+            ),
+          ),
+        ],
+      ),
+    );
+    _terminalClipboardNoticeController = controller;
+    unawaited(controller.closed.then<void>((_) {
+      if (identical(_terminalClipboardNoticeController, controller)) {
+        _terminalClipboardNoticeController = null;
+        _terminalClipboardNotice.noticeClosed();
+      }
+    }));
+  }
+
+  void _handleTerminalClipboardNegativeAction() {
+    final request = _terminalClipboardNotice.claimCurrentAction();
+    if (request == null) return;
+    if (request.persistAllowed) {
+      unawaited(_declineTerminalClipboardWrite());
+    } else {
+      _closeTerminalClipboardNotice();
+    }
+  }
+
+  void _handleTerminalClipboardPositiveAction() {
+    final request = _terminalClipboardNotice.claimCurrentAction();
+    if (request == null) return;
+    unawaited(_completeTerminalClipboardWrite(request));
+  }
+
+  bool get _canWriteTerminalClipboard =>
+      _canHandleTerminalClipboardWriteRequest &&
+      !_ffi.closed &&
+      _ffi.ffiModel.permissions['clipboard'] != false;
+
+  void _handleTerminalClipboardWriteSucceeded(String _) {
+    _closeTerminalClipboardNotice();
+  }
+
+  Future<void> _declineTerminalClipboardWrite() async {
+    try {
+      await bind.mainSetLocalOption(
+        key: kOptionAllowTerminalClipboardWrite,
+        value: kTerminalClipboardWriteDenied,
+      );
+    } catch (error) {
+      debugPrint(
+          '[TerminalPage] Failed to save terminal clipboard permission: $error');
+      return;
+    } finally {
+      _terminalClipboardNotice.releaseAction();
+    }
+    _closeTerminalClipboardNotice();
+  }
+
+  Future<void> _completeTerminalClipboardWrite(
+    TerminalClipboardNoticeRequest<int> request,
+  ) async {
+    var completed = false;
+    try {
+      completed = await completeTerminalClipboardWrite(
+        clipboardText: request.text,
+        canWrite: () => _canWriteTerminalClipboard,
+        writeClipboard: writeTerminalClipboard,
+        persistAllowed: request.persistAllowed
+            ? () => bind.mainSetLocalOption(
+                  key: kOptionAllowTerminalClipboardWrite,
+                  value: kTerminalClipboardWriteAllowed,
+                )
+            : null,
+      );
+    } catch (error) {
+      debugPrint(
+          '[TerminalPage] Failed to complete terminal clipboard write: $error');
+    } finally {
+      _terminalClipboardNotice.releaseAction();
+    }
+    if (!completed) return;
+    _closeTerminalClipboardNotice();
+  }
+
+  void _closeTerminalClipboardNotice() {
+    if (!_terminalClipboardNotice.beginClose()) return;
+    final controller = _terminalClipboardNoticeController;
+    if (controller == null) {
+      debugPrint('[TerminalPage] Clipboard notice controller is missing');
+      _terminalClipboardNotice.noticeClosed();
+      return;
+    }
+    controller.close();
+  }
+
  @override
  void dispose() {
    // Unregister terminal model from FFI
    _ffi.unregisterTerminalModel(widget.terminalId);
    _terminalModel.dispose();
    _keyboardDebounce?.cancel();
+    _terminalClipboardNotice.clear();
+    _terminalClipboardNoticeController?.close();
    WidgetsBinding.instance.removeObserver(this);
    super.dispose();
    TerminalConnectionManager.releaseConnection(widget.id);
@@ -234,12 +432,12 @@ class _TerminalPageState extends State<TerminalPage>
              child: LayoutBuilder(
                builder: (context, constraints) {
                  final heightPx = constraints.maxHeight;
-                  return TerminalView(
-                    _terminalModel.terminal,
+                  return _buildTerminalViewForPlatform(
+                    reportMouseInput: isWebDesktop || isAndroid,
+                    reportTouchInput: isIOS,
+                    terminal: _terminalModel.terminal,
                    controller: _terminalModel.terminalController,
-                    autofocus: true,
                    textStyle: _getTerminalStyle(),
-                    backgroundOpacity: 0.7,
                    // The following comment is from xterm.dart source code:
                    // Workaround to detect delete key for platforms and IMEs that do not
                    // emit a hardware delete event. Preferred on mobile platforms. [false] by
--- a/flutter/lib/models/rustdesk_terminal.dart
+++ b/flutter/lib/models/rustdesk_terminal.dart
@@ -1,7 +1,108 @@
+import 'dart:async';
+import 'dart:convert';
+
+import 'package:flutter/foundation.dart';
 import 'package:xterm/xterm.dart';

+enum TerminalClipboardWritePermission { denied, unconfigured, allowed }
+
 class RustDeskTerminal extends Terminal {
-  RustDeskTerminal({super.maxLines});
+  RustDeskTerminal({
+    super.maxLines,
+    required TerminalClipboardWritePermission Function()
+        clipboardWritePermission,
+    required Future<bool> Function(String) onClipboardWrite,
+    ValueChanged<String>? onClipboardWriteBlocked,
+    ValueChanged<String>? onClipboardWriteSucceeded,
+  })  : _clipboardWritePermission = clipboardWritePermission,
+        _onClipboardWrite = onClipboardWrite,
+        _onClipboardWriteBlocked = onClipboardWriteBlocked,
+        _onClipboardWriteSucceeded = onClipboardWriteSucceeded {
+    onPrivateOSC = _handlePrivateOsc;
+  }
+
+  static const _clipboardOscCode = '52';
+  static const _systemClipboardSelection = 'c';
+  // Match the terminal helper's existing payload safety ceiling.
+  static const _maxClipboardWriteBytes = 16 * 1024 * 1024;
+  static const _base64InputBytesPerBlock = 3;
+  static const _base64EncodedCharsPerBlock = 4;
+  static final _osc52Selection = RegExp(r'^[cpqs0-7]*$');
+  final TerminalClipboardWritePermission Function() _clipboardWritePermission;
+  final Future<bool> Function(String) _onClipboardWrite;
+  final ValueChanged<String>? _onClipboardWriteBlocked;
+  final ValueChanged<String>? _onClipboardWriteSucceeded;
+
+  bool get isClipboardWriteAllowed =>
+      _clipboardWritePermission() == TerminalClipboardWritePermission.allowed;
+
+  void _handlePrivateOsc(String code, List<String> args) {
+    if (code != _clipboardOscCode) return;
+    if (args.length != 2 || !_osc52Selection.hasMatch(args.first)) {
+      debugPrint('[RustDeskTerminal] Rejected malformed OSC 52 command');
+      return;
+    }
+    if (args.last == '?') {
+      debugPrint('[RustDeskTerminal] Rejected OSC 52 clipboard query');
+      return;
+    }
+    final permission = _clipboardWritePermission();
+    if (permission == TerminalClipboardWritePermission.denied) {
+      debugPrint('[RustDeskTerminal] Rejected unauthorized OSC 52 write');
+      return;
+    }
+    final selection = args.first;
+    if (selection.isNotEmpty &&
+        !selection.contains(_systemClipboardSelection)) {
+      debugPrint('[RustDeskTerminal] Ignored unsupported OSC 52 selection');
+      return;
+    }
+    if (selection.replaceAll(_systemClipboardSelection, '').isNotEmpty) {
+      debugPrint('[RustDeskTerminal] Ignored unsupported OSC 52 selections');
+    }
+    final text = _decodeClipboardPayload(args.last);
+    if (text == null) return;
+    if (permission == TerminalClipboardWritePermission.unconfigured) {
+      debugPrint('[RustDeskTerminal] Blocked OSC 52 write pending consent');
+      _onClipboardWriteBlocked?.call(text);
+      return;
+    }
+    unawaited(_writeClipboard(text));
+  }
+
+  Future<void> _writeClipboard(String text) async {
+    final succeeded = await _onClipboardWrite(text);
+    if (succeeded) {
+      _onClipboardWriteSucceeded?.call(text);
+      return;
+    }
+    debugPrint(
+        '[RustDeskTerminal] OSC 52 clipboard write requires interaction');
+    _onClipboardWriteBlocked?.call(text);
+  }
+
+  String? _decodeClipboardPayload(String payload) {
+    if (payload.length > _maxBase64EncodedLength(_maxClipboardWriteBytes)) {
+      debugPrint('[RustDeskTerminal] Rejected oversized OSC 52 payload');
+      return null;
+    }
+    try {
+      final bytes = base64.decode(payload);
+      if (bytes.length > _maxClipboardWriteBytes) {
+        debugPrint('[RustDeskTerminal] Rejected oversized OSC 52 payload');
+        return null;
+      }
+      return utf8.decode(bytes);
+    } on FormatException {
+      debugPrint('[RustDeskTerminal] Rejected malformed OSC 52 payload');
+      return null;
+    }
+  }
+
+  static int _maxBase64EncodedLength(int maxBytes) =>
+      ((maxBytes + _base64InputBytesPerBlock - 1) ~/
+          _base64InputBytesPerBlock) *
+      _base64EncodedCharsPerBlock;

  @override
  void eraseScrollbackOnly() {
--- a/flutter/lib/models/terminal_clipboard_writer.dart
+++ b/flutter/lib/models/terminal_clipboard_writer.dart
@@ -0,0 +1,15 @@
+import 'package:flutter/foundation.dart';
+import 'package:flutter/services.dart';
+
+Future<bool> writeTerminalClipboardPlatform(
+  String text, {
+  bool userInitiated = false,
+}) async {
+  try {
+    await Clipboard.setData(ClipboardData(text: text));
+    return true;
+  } catch (error) {
+    debugPrint('[Terminal] Failed to write clipboard: $error');
+    return false;
+  }
+}
--- a/flutter/lib/models/terminal_clipboard_writer_web.dart
+++ b/flutter/lib/models/terminal_clipboard_writer_web.dart
@@ -0,0 +1,29 @@
+import 'dart:js_interop';
+
+import 'package:flutter/foundation.dart';
+
+const _writeTerminalClipboardCommand = 'write_terminal_clipboard';
+
+@JS('setByName')
+external JSPromise<JSBoolean> _setByName(
+  JSString name,
+  JSString value,
+  JSBoolean userInitiated,
+);
+
+Future<bool> writeTerminalClipboardPlatform(
+  String text, {
+  bool userInitiated = false,
+}) async {
+  try {
+    final result = await _setByName(
+      _writeTerminalClipboardCommand.toJS,
+      text.toJS,
+      userInitiated.toJS,
+    ).toDart;
+    return result.toDart;
+  } catch (error) {
+    debugPrint('[Terminal] Failed to write Web clipboard: $error');
+    return false;
+  }
+}
--- a/flutter/lib/models/terminal_copy_shortcut.dart
+++ b/flutter/lib/models/terminal_copy_shortcut.dart
@@ -3,20 +3,130 @@ import 'dart:async';
 import 'package:flutter/foundation.dart';
 import 'package:flutter/services.dart';
 import 'package:flutter/widgets.dart';
+import 'package:flutter_hbb/consts.dart';
 import 'package:xterm/xterm.dart';

+import 'terminal_clipboard_writer.dart'
+    if (dart.library.html) 'terminal_clipboard_writer_web.dart';
+
 const _controlShiftVPasteShortcut = SingleActivator(
  LogicalKeyboardKey.keyV,
  control: true,
  shift: true,
 );

-Future<void> writeTerminalClipboard(String text) async {
-  try {
-    await Clipboard.setData(ClipboardData(text: text));
-  } catch (error) {
-    debugPrint('[Terminal] Failed to write clipboard: $error');
+typedef TerminalClipboardWriter = Future<bool> Function(
+  String text, {
+  required bool userInitiated,
+});
+
+class TerminalClipboardNoticeRequest<T> {
+  const TerminalClipboardNoticeRequest({
+    required this.source,
+    required this.text,
+    required this.persistAllowed,
+  });
+
+  final T source;
+  final String text;
+  final bool persistAllowed;
+
+  String get actionKey => persistAllowed ? 'Enable' : 'Copy to clipboard';
+
+  String get negativeActionKey => persistAllowed ? 'Decline' : 'Dismiss';
+}
+
+const kTerminalClipboardNoticeMessageKey = 'terminal-clipboard-write-tip';
+
+class TerminalClipboardNoticeCoordinator<T> extends ChangeNotifier {
+  TerminalClipboardNoticeRequest<T>? _current;
+  bool _noticeVisible = false;
+  bool _actionInProgress = false;
+
+  TerminalClipboardNoticeRequest<T>? get current => _current;
+  bool get canClaimAction =>
+      _noticeVisible && !_actionInProgress && _current != null;
+
+  TerminalClipboardNoticeRequest<T>? currentForSource(T source) {
+    final current = _current;
+    if (current == null || current.source != source) return null;
+    return current;
  }
+
+  TerminalClipboardNoticeRequest<T>? recordBlocked({
+    required T source,
+    required String text,
+    required String option,
+    required bool Function(T source) canWrite,
+  }) {
+    if (!canWrite(source)) return null;
+    final requestAllowsPersistence =
+        option == kTerminalClipboardWriteUnconfigured;
+    if (option != kTerminalClipboardWriteAllowed && !requestAllowsPersistence) {
+      return null;
+    }
+    if (_noticeVisible && _actionInProgress) return null;
+    final wasVisible = _noticeVisible;
+    final persistAllowed =
+        wasVisible ? _current?.persistAllowed : requestAllowsPersistence;
+    final request = TerminalClipboardNoticeRequest(
+      source: source,
+      text: text,
+      persistAllowed: persistAllowed ?? requestAllowsPersistence,
+    );
+    _current = request;
+    if (wasVisible) return null;
+    _noticeVisible = true;
+    return request;
+  }
+
+  TerminalClipboardNoticeRequest<T>? claimCurrentAction() {
+    if (!canClaimAction) return null;
+    final current = _current;
+    if (current == null) return null;
+    _actionInProgress = true;
+    notifyListeners();
+    return current;
+  }
+
+  void releaseAction() {
+    if (!_actionInProgress) return;
+    _actionInProgress = false;
+    notifyListeners();
+  }
+
+  bool beginClose() {
+    if (!_noticeVisible) return false;
+    _actionInProgress = true;
+    notifyListeners();
+    return true;
+  }
+
+  void noticeClosed() => clear();
+
+  void clear() {
+    _current = null;
+    _noticeVisible = false;
+    _actionInProgress = false;
+  }
+}
+
+Future<bool> writeTerminalClipboard(
+  String text, {
+  bool userInitiated = false,
+}) =>
+    writeTerminalClipboardPlatform(text, userInitiated: userInitiated);
+
+Future<bool> completeTerminalClipboardWrite({
+  required String clipboardText,
+  required bool Function() canWrite,
+  required TerminalClipboardWriter writeClipboard,
+  Future<void> Function()? persistAllowed,
+}) async {
+  if (!canWrite()) return false;
+  if (!await writeClipboard(clipboardText, userInitiated: true)) return false;
+  await persistAllowed?.call();
+  return true;
 }

 Map<ShortcutActivator, Intent>? platformTerminalShortcuts() {
@@ -68,7 +178,7 @@ FocusOnKeyEventCallback terminalCopyHandler(
        if (selection != null && !selection.isCollapsed) {
          if (event is KeyDownEvent) {
            final text = terminal.buffer.getText(selection);
-            unawaited(writeTerminalClipboard(text));
+            unawaited(writeTerminalClipboard(text, userInitiated: true));
          }
          return KeyEventResult.handled;
        }
--- a/flutter/lib/models/terminal_model.dart
+++ b/flutter/lib/models/terminal_model.dart
@@ -11,8 +11,38 @@ import 'input_modifier_utils.dart';
 import 'model.dart';
 import 'platform_model.dart';
 import 'rustdesk_terminal.dart';
+import 'terminal_copy_shortcut.dart';
 import 'terminal_mouse_handler.dart';

+bool canConfigureTerminalClipboardPermission({
+  required bool settingsDisabled,
+  required bool optionFixed,
+}) =>
+    !settingsDisabled && !optionFixed;
+
+bool canHandleTerminalClipboardWriteRequest({
+  required String localOption,
+  required bool canConfigurePermission,
+}) =>
+    canConfigurePermission || localOption == kTerminalClipboardWriteAllowed;
+
+TerminalClipboardWritePermission terminalClipboardWritePermission(
+  String localOption, {
+  required bool remoteClipboardEnabled,
+  bool canRequestConsent = true,
+}) {
+  if (!remoteClipboardEnabled) {
+    return TerminalClipboardWritePermission.denied;
+  }
+  if (localOption == kTerminalClipboardWriteAllowed) {
+    return TerminalClipboardWritePermission.allowed;
+  }
+  if (localOption == kTerminalClipboardWriteUnconfigured && canRequestConsent) {
+    return TerminalClipboardWritePermission.unconfigured;
+  }
+  return TerminalClipboardWritePermission.denied;
+}
+
 class TerminalModel with ChangeNotifier {
  final String id; // peer id
  final FFI parent;
@@ -62,6 +92,9 @@ class TerminalModel with ChangeNotifier {
  /// The listener (typically TerminalPage) can use this to auto-close the tab/page.
  VoidCallback? onClosed;

+  ValueChanged<String>? onClipboardWriteBlocked;
+  ValueChanged<String>? onClipboardWriteSucceeded;
+
  Future<void> _handleInput(String data) async {
    // xterm can complete asynchronous input after the Flutter page has gone
    // away. Stop before reading or clearing widget-owned modifier state.
@@ -130,7 +163,19 @@ class TerminalModel with ChangeNotifier {
  }

  TerminalModel(this.parent, [this.terminalId = 0]) : id = parent.id {
-    terminal = RustDeskTerminal(maxLines: 10000);
+    terminal = RustDeskTerminal(
+      maxLines: 10000,
+      onClipboardWrite: writeTerminalClipboard,
+      clipboardWritePermission: () => terminalClipboardWritePermission(
+        bind.mainGetLocalOption(key: kOptionAllowTerminalClipboardWrite),
+        remoteClipboardEnabled:
+            parent.ffiModel.permissions['clipboard'] != false,
+        canRequestConsent: onClipboardWriteBlocked != null,
+      ),
+      onClipboardWriteBlocked: (text) => onClipboardWriteBlocked?.call(text),
+      onClipboardWriteSucceeded: (text) =>
+          onClipboardWriteSucceeded?.call(text),
+    );
    terminal.mouseHandler = const WheelButtonFixMouseHandler();
    terminalController = TerminalController();

@@ -593,6 +638,8 @@ class TerminalModel with ChangeNotifier {
    clearAltLock = null;
    onResizeExternal = null;
    onClosed = null;
+    onClipboardWriteBlocked = null;
+    onClipboardWriteSucceeded = null;
    // Clear buffers to free memory
    _inputBuffer.clear();
    _pendingOutputChunks.clear();
--- a/flutter/lib/models/terminal_mouse_drag_reporter.dart
+++ b/flutter/lib/models/terminal_mouse_drag_reporter.dart
@@ -62,13 +62,17 @@ class TerminalMouseDragReporter {
  var _ownsControllerSuspension = false;
  var _releasePending = false;
  var _reporting = false;
+  var _dragged = false;

  bool handleDown(
    PointerDownEvent event,
    Terminal terminal,
-    TerminalViewState? terminalView,
-  ) {
-    if (!_isPrimaryMouse(event) || !_reportsDrag(terminal.mouseMode)) {
+    TerminalViewState? terminalView, {
+    bool reportTouchInput = false,
+    bool deferReport = false,
+  }) {
+    if (!_isPrimaryPointer(event, reportTouchInput) ||
+        !_reportsDrag(terminal.mouseMode)) {
      return false;
    }
    if (terminalView == null || terminalView.widget.readOnly) return false;
@@ -83,14 +87,33 @@ class TerminalMouseDragReporter {
    _pointerId = event.pointer;
    _controller = controller;
    _ownsControllerSuspension = true;
-    _releasePending = true;
-    _reporting = true;
+    _releasePending = !deferReport;
+    _reporting = !deferReport;
+    _dragged = false;
    controller.setSuspendPointerInput(true);
    _clearSelection(controller);
    final position = _cellAt(event, terminalView);
    _lastReportedPosition = position;
+    if (!deferReport) {
+      terminal.textInput(
+        _report(terminal.mouseReportMode, position),
+      );
+    }
+    return true;
+  }
+
+  bool activateDeferredDown(Terminal terminal) {
+    if (_pointerId == null ||
+        _controller == null ||
+        _releasePending ||
+        !_reportsDrag(terminal.mouseMode)) {
+      return false;
+    }
+    _releasePending = true;
+    _reporting = true;
+    _clearSelection(_controller);
    terminal.textInput(
-      _report(terminal.mouseReportMode, position),
+      _report(terminal.mouseReportMode, _lastReportedPosition),
    );
    return true;
  }
@@ -98,26 +121,36 @@ class TerminalMouseDragReporter {
  bool handleMove(
    PointerMoveEvent event,
    Terminal terminal,
-    TerminalViewState? terminalView,
-  ) {
+    TerminalViewState? terminalView, {
+    void Function(bool dragged)? beforeRelease,
+    void Function()? onCancel,
+  }) {
    if (event.pointer != _pointerId) return false;
    if (terminalView == null) {
+      onCancel?.call();
      cancel();
      return true;
    }
    final reportsDrag = _reportsDrag(terminal.mouseMode);
-    if (!_isPrimaryMouse(event)) {
+    if (!_hasPrimaryButton(event)) {
      if (_releasePending && reportsDrag) {
-        _reportRelease(
+        _finishRelease(
+          event,
          terminal,
-          _reporting ? _cellAt(event, terminalView) : _lastReportedPosition,
+          terminalView,
+          beforeRelease: beforeRelease,
        );
+      } else {
+        onCancel?.call();
      }
      cancel();
      return true;
    }
    if (!_reporting || !reportsDrag) {
-      if (!reportsDrag) _releasePending = false;
+      if (!reportsDrag && _releasePending) {
+        _releasePending = false;
+        onCancel?.call();
+      }
      _reporting = false;
      // Keep ownership until the matching end event to suppress local selection.
      final controller = _controller;
@@ -126,7 +159,7 @@ class TerminalMouseDragReporter {
    }

    final position = _cellAt(event, terminalView);
-    _lastReportedPosition = position;
+    _recordPosition(position);
    terminal.textInput(
      _report(terminal.mouseReportMode, position, motion: true),
    );
@@ -138,16 +171,22 @@ class TerminalMouseDragReporter {
  bool handleEnd(
    PointerEvent event,
    Terminal terminal,
-    TerminalViewState? terminalView,
-  ) {
+    TerminalViewState? terminalView, {
+    void Function(bool dragged)? beforeRelease,
+    void Function()? onCancel,
+  }) {
    if (event.pointer != _pointerId) return false;
    if (terminalView != null &&
        _releasePending &&
        _reportsDrag(terminal.mouseMode)) {
-      _reportRelease(
+      _finishRelease(
+        event,
        terminal,
-        _reporting ? _cellAt(event, terminalView) : _lastReportedPosition,
+        terminalView,
+        beforeRelease: beforeRelease,
      );
+    } else {
+      onCancel?.call();
    }
    _clearSelection(_controller);
    final controller = _controller;
@@ -172,6 +211,7 @@ class TerminalMouseDragReporter {
    _ownsControllerSuspension = false;
    _releasePending = false;
    _reporting = false;
+    _dragged = false;
  }

  void updateController(TerminalController controller) {
@@ -203,6 +243,24 @@ class TerminalMouseDragReporter {
    );
  }

+  void _finishRelease(
+    PointerEvent event,
+    Terminal terminal,
+    TerminalViewState terminalView, {
+    void Function(bool dragged)? beforeRelease,
+  }) {
+    final position =
+        _reporting ? _cellAt(event, terminalView) : _lastReportedPosition;
+    if (_reporting) _recordPosition(position);
+    beforeRelease?.call(_dragged);
+    _reportRelease(terminal, position);
+  }
+
+  void _recordPosition(CellOffset position) {
+    _dragged = _dragged || position != _lastReportedPosition;
+    _lastReportedPosition = position;
+  }
+
  CellOffset _cellAt(PointerEvent event, TerminalViewState terminalView) {
    final renderTerminal = terminalView.renderTerminal;
    return renderTerminal.getCellOffset(
@@ -210,9 +268,13 @@ class TerminalMouseDragReporter {
    );
  }

-  bool _isPrimaryMouse(PointerEvent event) =>
-      event.kind == PointerDeviceKind.mouse &&
-      (event.buttons & kPrimaryMouseButton) == kPrimaryMouseButton;
+  bool _isPrimaryPointer(PointerEvent event, bool reportTouchInput) =>
+      (event.kind == PointerDeviceKind.mouse ||
+          reportTouchInput && event.kind == PointerDeviceKind.touch) &&
+      _hasPrimaryButton(event);
+
+  bool _hasPrimaryButton(PointerEvent event) =>
+      (event.buttons & kPrimaryButton) == kPrimaryButton;

  bool _reportsDrag(MouseMode mode) =>
      mode == MouseMode.upDownScrollDrag || mode == MouseMode.upDownScrollMove;
--- a/flutter/lib/models/terminal_mouse_handler.dart
+++ b/flutter/lib/models/terminal_mouse_handler.dart
@@ -1,45 +1,17 @@
 import 'dart:async';

+import 'package:flutter/foundation.dart';
 import 'package:flutter/gestures.dart';
 import 'package:flutter/widgets.dart';
 import 'package:xterm/xterm.dart';

+import 'platform_model.dart';
+import 'rustdesk_terminal.dart';
 import 'terminal_copy_shortcut.dart';
 import 'terminal_mouse_drag_reporter.dart';

-/// xterm 4.0.0 encodes wheel buttons as 68..71; the extra bit reads as a Shift
-/// modifier, so strict full-screen apps ignore the report and never scroll.
-/// Upstream fix: TerminalStudio/xterm.dart#238.
-class WheelButtonFixMouseHandler implements TerminalMouseHandler {
-  const WheelButtonFixMouseHandler({this.positionProvider});
-
-  final CellOffset? Function()? positionProvider;
-
-  @override
-  String? call(TerminalMouseEvent event) {
-    if (!event.button.isWheel) {
-      return defaultMouseHandler(event);
-    }
-    // Same gate as UpDownMouseHandler: only the scroll modes report a wheel,
-    // and a wheel release is never reported, so the report is always a press.
-    if (!event.state.mouseMode.reportScroll ||
-        event.buttonState == TerminalMouseButtonState.up) {
-      return null;
-    }
-    return _reportWheel(event);
-  }
-
-  String _reportWheel(TerminalMouseEvent event) {
-    // Wheel buttons 4..7 go on the wire as 64..67, but `id` is 64 + 4..7.
-    final button = event.button.id - 4;
-    final position = positionProvider?.call() ?? event.position;
-    return encodeTerminalMouseReport(
-      event.state.mouseReportMode,
-      button,
-      position,
-    );
-  }
-}
+part 'terminal_mouse_handler_input.dart';
+part 'terminal_web_clipboard_gesture.dart';

 class TerminalMouseInteraction extends StatefulWidget {
  const TerminalMouseInteraction(
@@ -47,6 +19,12 @@ class TerminalMouseInteraction extends StatefulWidget {
    super.key,
    required this.controller,
    this.focusNode,
+    this.autofocus = false,
+    this.textStyle = const TerminalStyle(),
+    this.deleteDetection = false,
+    this.reportTouchInput = false,
+    this.shortcuts,
+    this.onKeyEvent,
    this.backgroundOpacity = 1,
    this.padding,
    this.onSecondaryTapDown,
@@ -55,6 +33,12 @@ class TerminalMouseInteraction extends StatefulWidget {
  final Terminal terminal;
  final TerminalController controller;
  final FocusNode? focusNode;
+  final bool autofocus;
+  final TerminalStyle textStyle;
+  final bool deleteDetection;
+  final bool reportTouchInput;
+  final Map<ShortcutActivator, Intent>? shortcuts;
+  final FocusOnKeyEventCallback? onKeyEvent;
  final double backgroundOpacity;
  final EdgeInsets? padding;
  final void Function(TapDownDetails, CellOffset)? onSecondaryTapDown;
@@ -81,8 +65,13 @@ class _TerminalMouseInteractionState extends State<TerminalMouseInteraction> {
  Buffer? _selectionBuffer;
  int? _selectionPointerId;
  Timer? _selectionScrollTimer;
+  Timer? _pendingTouchMouseTimer;
+  PointerDownEvent? _pendingTouchMouseDown;
  var _selectionHasScrolled = false;
  var _scrollDirection = _noScroll;
+  // xterm can finish its tap callbacks after the raw drag was reported.
+  var _suppressXtermLeftButton = false;
+  var _terminalClipboardGesturePrepared = false;
  TerminalViewState? get _terminalView => _terminalViewKey.currentState;

  @override
@@ -90,6 +79,7 @@ class _TerminalMouseInteractionState extends State<TerminalMouseInteraction> {
    super.initState();
    _mouseHandler = WheelButtonFixMouseHandler(
      positionProvider: _cellAtPointer,
+      suppressLeftButton: kIsWeb ? _consumeXtermLeftButtonSuppression : null,
    );
    _installMouseHandler(widget.terminal);
  }
@@ -100,10 +90,15 @@ class _TerminalMouseInteractionState extends State<TerminalMouseInteraction> {
    final terminalChanged = !identical(oldWidget.terminal, widget.terminal);
    final controllerChanged =
        !identical(oldWidget.controller, widget.controller);
+    final touchInputChanged =
+        oldWidget.reportTouchInput != widget.reportTouchInput;
+    if (!terminalChanged && !controllerChanged && !touchInputChanged) return;
+    _cancelPendingTouchMouseDrag();
    if (!terminalChanged && !controllerChanged) return;
    if (controllerChanged && !terminalChanged) {
      _mouseDrag.updateController(widget.controller);
    } else {
+      _discardPendingTerminalClipboardWrites();
      _mouseDrag.cancel();
    }
    _clearSelectionDrag();
@@ -123,46 +118,18 @@ class _TerminalMouseInteractionState extends State<TerminalMouseInteraction> {
    }
  }

-  CellOffset? _cellAtPointer() {
-    final terminalView = _terminalView;
-    final pointerPosition = _pointerPosition;
-    if (terminalView == null || pointerPosition == null) return null;
-    final renderTerminal = terminalView.renderTerminal;
-    return renderTerminal.getCellOffset(
-      renderTerminal.globalToLocal(pointerPosition),
-    );
-  }
-
-  void _updatePointerPosition(PointerEvent event) =>
-      _pointerPosition = event.position;
-
-  void _handlePointerDown(PointerDownEvent event) {
-    _updatePointerPosition(event);
-    if (_mouseDrag.handleDown(event, widget.terminal, _terminalView)) {
-      _clearSelectionDrag();
-      return;
-    }
-    if (event.kind != PointerDeviceKind.mouse ||
-        (event.buttons & kPrimaryMouseButton) != kPrimaryMouseButton) {
-      return;
-    }
-    _clearSelectionDrag();
-    final terminalView = _terminalView;
-    if (terminalView == null) return;
-    final renderTerminal = terminalView.renderTerminal;
-    final localPosition = renderTerminal.globalToLocal(event.position);
-    final selectionBuffer = widget.terminal.buffer;
-    _selectionPointerId = event.pointer;
-    _selectionBase = selectionBuffer.createAnchorFromOffset(
-      renderTerminal.getCellOffset(localPosition),
-    );
-    _selectionBuffer = selectionBuffer;
-    _selectionPointer = localPosition;
-  }
-
  void _handlePointerMove(PointerMoveEvent event) {
    _updatePointerPosition(event);
-    if (_mouseDrag.handleMove(event, widget.terminal, _terminalView)) return;
+    if (_handlePendingTouchMove(event)) return;
+    if (_mouseDrag.handleMove(
+      event,
+      widget.terminal,
+      _terminalView,
+      beforeRelease: _finishTerminalClipboardWrite,
+      onCancel: _cancelTerminalClipboardWrite,
+    )) {
+      return;
+    }
    if (event.pointer != _selectionPointerId) return;
    if (event.kind != PointerDeviceKind.mouse ||
        (event.buttons & kPrimaryMouseButton) != kPrimaryMouseButton) {
@@ -241,8 +208,28 @@ class _TerminalMouseInteractionState extends State<TerminalMouseInteraction> {

  void _handlePointerEnd(PointerEvent event) {
    _updatePointerPosition(event);
-    if (!_mouseDrag.handleEnd(event, widget.terminal, _terminalView) &&
-        event.pointer != _selectionPointerId) return;
+    final pendingTouch = _pendingTouchMouseDown;
+    if (pendingTouch != null && pendingTouch.pointer == event.pointer) {
+      final movedBeyondSlop =
+          (event.position - pendingTouch.position).distance > kTouchSlop;
+      if (event is PointerUpEvent && !movedBeyondSlop) {
+        _activatePendingTouchMouseDrag(cancelOnFailure: false);
+      } else {
+        _takePendingTouchMouseDrag(pointer: event.pointer);
+      }
+    }
+    final handledByMouseDrag = _mouseDrag.handleEnd(
+      event,
+      widget.terminal,
+      _terminalView,
+      beforeRelease: event is PointerUpEvent
+          ? _finishTerminalClipboardWrite
+          : (_) => _cancelTerminalClipboardWrite(),
+      onCancel: _cancelTerminalClipboardWrite,
+    );
+    if (!handledByMouseDrag && event.pointer != _selectionPointerId) {
+      return;
+    }
    if (_selectionHasScrolled) _scrollSelection(scroll: false);
    _clearSelectionDrag();
  }
@@ -265,6 +252,8 @@ class _TerminalMouseInteractionState extends State<TerminalMouseInteraction> {

  @override
  void dispose() {
+    _discardPendingTerminalClipboardWrites();
+    _cancelPendingTouchMouseDrag();
    _mouseDrag.cancel();
    _clearSelectionDrag();
    _restoreMouseHandler(widget.terminal);
@@ -290,10 +279,14 @@ class _TerminalMouseInteractionState extends State<TerminalMouseInteraction> {
        controller: widget.controller,
        scrollController: _scrollController,
        focusNode: widget.focusNode,
+        autofocus: widget.autofocus,
+        textStyle: widget.textStyle,
+        deleteDetection: widget.deleteDetection,
        backgroundOpacity: widget.backgroundOpacity,
        padding: widget.padding,
-        shortcuts: platformTerminalShortcuts(),
-        onKeyEvent: terminalCopyHandler(widget.terminal, widget.controller),
+        shortcuts: widget.shortcuts ?? platformTerminalShortcuts(),
+        onKeyEvent: widget.onKeyEvent ??
+            terminalCopyHandler(widget.terminal, widget.controller),
        onSecondaryTapDown: widget.onSecondaryTapDown,
      ),
    );
--- a/flutter/lib/models/terminal_mouse_handler_input.dart
+++ b/flutter/lib/models/terminal_mouse_handler_input.dart
@@ -0,0 +1,162 @@
+part of 'terminal_mouse_handler.dart';
+
+/// xterm 4.0.0 encodes wheel buttons as 68..71; the extra bit reads as a Shift
+/// modifier, so strict full-screen apps ignore the report and never scroll.
+/// Upstream fix: TerminalStudio/xterm.dart#238.
+class WheelButtonFixMouseHandler implements TerminalMouseHandler {
+  const WheelButtonFixMouseHandler({
+    this.positionProvider,
+    this.suppressLeftButton,
+  });
+
+  final CellOffset? Function()? positionProvider;
+  final bool Function(TerminalMouseButtonState)? suppressLeftButton;
+
+  @override
+  String? call(TerminalMouseEvent event) {
+    if (!event.button.isWheel) {
+      if (event.button == TerminalMouseButton.left &&
+          suppressLeftButton?.call(event.buttonState) == true) {
+        return null;
+      }
+      return defaultMouseHandler(event);
+    }
+    // Same gate as UpDownMouseHandler: only the scroll modes report a wheel,
+    // and a wheel release is never reported, so the report is always a press.
+    if (!event.state.mouseMode.reportScroll ||
+        event.buttonState == TerminalMouseButtonState.up) {
+      return null;
+    }
+    return _reportWheel(event);
+  }
+
+  String _reportWheel(TerminalMouseEvent event) {
+    // Wheel buttons 4..7 go on the wire as 64..67, but `id` is 64 + 4..7.
+    final button = event.button.id - 4;
+    final position = positionProvider?.call() ?? event.position;
+    return encodeTerminalMouseReport(
+      event.state.mouseReportMode,
+      button,
+      position,
+    );
+  }
+}
+
+extension _TerminalMouseInput on _TerminalMouseInteractionState {
+  CellOffset? _cellAtPointer() {
+    final terminalView = _terminalView;
+    final pointerPosition = _pointerPosition;
+    if (terminalView == null || pointerPosition == null) return null;
+    final renderTerminal = terminalView.renderTerminal;
+    return renderTerminal.getCellOffset(
+      renderTerminal.globalToLocal(pointerPosition),
+    );
+  }
+
+  void _updatePointerPosition(PointerEvent event) =>
+      _pointerPosition = event.position;
+
+  void _handlePointerDown(PointerDownEvent event) {
+    _updatePointerPosition(event);
+    _suppressXtermLeftButton = false;
+    if (_startPendingTouchMouseDrag(event)) return;
+    if (_mouseDrag.handleDown(event, widget.terminal, _terminalView)) {
+      _prepareTerminalClipboardWrite();
+      if (kIsWeb) _suppressXtermLeftButton = true;
+      _clearSelectionDrag();
+      return;
+    }
+    if (event.kind != PointerDeviceKind.mouse ||
+        (event.buttons & kPrimaryMouseButton) != kPrimaryMouseButton) {
+      return;
+    }
+    _clearSelectionDrag();
+    final terminalView = _terminalView;
+    if (terminalView == null) return;
+    final renderTerminal = terminalView.renderTerminal;
+    final localPosition = renderTerminal.globalToLocal(event.position);
+    final selectionBuffer = widget.terminal.buffer;
+    _selectionPointerId = event.pointer;
+    _selectionBase = selectionBuffer.createAnchorFromOffset(
+      renderTerminal.getCellOffset(localPosition),
+    );
+    _selectionBuffer = selectionBuffer;
+    _selectionPointer = localPosition;
+  }
+
+  bool _startPendingTouchMouseDrag(PointerDownEvent event) {
+    if (!widget.reportTouchInput ||
+        event.kind != PointerDeviceKind.touch ||
+        !_mouseDrag.handleDown(
+          event,
+          widget.terminal,
+          _terminalView,
+          reportTouchInput: true,
+          deferReport: true,
+        )) {
+      return false;
+    }
+    _pendingTouchMouseDown = event;
+    _pendingTouchMouseTimer = Timer(
+      kLongPressTimeout,
+      _activatePendingTouchMouseDrag,
+    );
+    return true;
+  }
+
+  bool _activatePendingTouchMouseDrag({
+    bool cancelOnFailure = true,
+  }) {
+    if (_takePendingTouchMouseDrag() == null) return false;
+    if (_mouseDrag.activateDeferredDown(widget.terminal)) {
+      _prepareTerminalClipboardWrite();
+      _clearSelectionDrag();
+      return true;
+    }
+    if (cancelOnFailure) _mouseDrag.cancel();
+    return false;
+  }
+
+  PointerDownEvent? _takePendingTouchMouseDrag({int? pointer}) {
+    final pending = _pendingTouchMouseDown;
+    if (pending == null || pointer != null && pointer != pending.pointer) {
+      return null;
+    }
+    _pendingTouchMouseTimer?.cancel();
+    _pendingTouchMouseTimer = null;
+    _pendingTouchMouseDown = null;
+    return pending;
+  }
+
+  void _cancelPendingTouchMouseDrag({
+    int? pointer,
+    bool deferCancel = false,
+  }) {
+    if (_takePendingTouchMouseDrag(pointer: pointer) == null) return;
+    if (deferCancel) {
+      scheduleMicrotask(_mouseDrag.cancel);
+    } else {
+      _mouseDrag.cancel();
+    }
+  }
+
+  bool _handlePendingTouchMove(PointerMoveEvent event) {
+    final pending = _pendingTouchMouseDown;
+    if (pending == null || pending.pointer != event.pointer) return false;
+    if ((event.position - pending.position).distance > kTouchSlop) {
+      _cancelPendingTouchMouseDrag(
+        pointer: event.pointer,
+        deferCancel: true,
+      );
+    }
+    return true;
+  }
+
+  bool _consumeXtermLeftButtonSuppression(TerminalMouseButtonState state) {
+    final suppress = _suppressXtermLeftButton;
+    if (state == TerminalMouseButtonState.up) {
+      _suppressXtermLeftButton = false;
+    }
+    return suppress;
+  }
+}
--- a/flutter/lib/models/terminal_web_clipboard_gesture.dart
+++ b/flutter/lib/models/terminal_web_clipboard_gesture.dart
@@ -0,0 +1,56 @@
+part of 'terminal_mouse_handler.dart';
+
+const _prepareTerminalClipboardCommand = 'prepare_terminal_clipboard';
+const _finishTerminalClipboardCommand = 'finish_terminal_clipboard';
+const _cancelTerminalClipboardCommand = 'cancel_terminal_clipboard';
+
+extension _TerminalWebClipboardGesture on _TerminalMouseInteractionState {
+  void _prepareTerminalClipboardWrite() {
+    if (!kIsWeb) return;
+    _cancelTerminalClipboardWrite();
+    final terminal = widget.terminal;
+    if (terminal is! RustDeskTerminal || !terminal.isClipboardWriteAllowed) {
+      return;
+    }
+    try {
+      ffiSetByName(_prepareTerminalClipboardCommand);
+      _terminalClipboardGesturePrepared = true;
+    } catch (error) {
+      debugPrint('[Terminal] Failed to prepare Web clipboard write: $error');
+    }
+  }
+
+  void _finishTerminalClipboardWrite(bool responseExpected) {
+    if (!_terminalClipboardGesturePrepared) return;
+    _terminalClipboardGesturePrepared = false;
+    if (!kIsWeb) return;
+    try {
+      ffiSetByName(
+        _finishTerminalClipboardCommand,
+        responseExpected ? 'true' : 'false',
+      );
+    } catch (error) {
+      debugPrint('[Terminal] Failed to finish Web clipboard write: $error');
+    }
+  }
+
+  void _cancelTerminalClipboardWrite() {
+    if (!_terminalClipboardGesturePrepared) return;
+    _terminalClipboardGesturePrepared = false;
+    _sendTerminalClipboardCancel();
+  }
+
+  void _discardPendingTerminalClipboardWrites() {
+    _cancelTerminalClipboardWrite();
+    _sendTerminalClipboardCancel();
+  }
+
+  void _sendTerminalClipboardCancel() {
+    if (!kIsWeb) return;
+    try {
+      ffiSetByName(_cancelTerminalClipboardCommand);
+    } catch (error) {
+      debugPrint('[Terminal] Failed to cancel Web clipboard write: $error');
+    }
+  }
+}