feat(terminal): add Ctrl and Alt toggles to mobile terminal keyboard (#15532)

* feat(terminal): add Ctrl toggle and Ctrl+X shortcut keys to mobile terminal floating keyboard

Signed-off-by: dongrencd <dongrencd@users.noreply.github.com>

* refactor(terminal): restructure keyboard layout with collapse button

- Move | from Row1 position 3 to Row1 end (aligned with collapse button)
- Remove ~ from Row2, add collapse button (∨/∧) after PgDn
- Row3: conditional render, add ~ and -, remove trailing placeholders
- Collapse state persisted via kOptionEnableShowTerminalCtrlKeys
- Row3 defaults to collapsed for compact layout

Signed-off-by: dongrencd <dongrencd@users.noreply.github.com>

* fix(terminal): restore trailing placeholders in Row3 for alignment

Row3 needs trailing placeholders to match Row1/Row2 width (348px)
so Ctrl aligns with Tab in Row2 and Esc in Row1.

Signed-off-by: dongrencd <dongrencd@users.noreply.github.com>

* fix(terminal): update mobile keyboard layout per review

Signed-off-by: dong.ren.cd <dong.ren.cd@tcl.com>

* fix(terminal): address mobile keyboard review regressions

Signed-off-by: dong.ren.cd <dong.ren.cd@tcl.com>

* fix(terminal): preserve ctrl-j newline mapping on mobile

Signed-off-by: dong.ren.cd <dong.ren.cd@tcl.com>

* fix(terminal): preserve pasted input with modifiers

Signed-off-by: dong.ren.cd <dong.ren.cd@tcl.com>

* fix(terminal): harden mobile modifier and paste input

Signed-off-by: dong.ren.cd <dong.ren.cd@tcl.com>

* fix(terminal): harden mobile paste shortcut handling

Signed-off-by: dong.ren.cd <dong.ren.cd@tcl.com>

* fix(terminal): preserve unicode graphemes under ctrl

* fix(terminal): avoid modifier scan for inactive locks

* fix(terminal): keep default hardware paste shortcuts

* fix(terminal): guard hardware paste with modifier locks

* fix(terminal): update mobile key button color role

---------

Signed-off-by: dongrencd <dongrencd@users.noreply.github.com>
Signed-off-by: dong.ren.cd <dong.ren.cd@tcl.com>
Co-authored-by: dongrencd <dongrencd@users.noreply.github.com>
Co-authored-by: dong.ren.cd <dong.ren.cd@tcl.com>

flutter/lib/models/input_modifier_utils.dart

@@ -1,4 +1,12 @@
 import 'package:flutter/services.dart';
+import 'package:flutter/widgets.dart';
+
+/// Identifies where terminal input originated so paste data can bypass all
+/// keyboard-only transformations.
+enum TerminalInputSource {
+  keyboard,
+  paste,
+}
 
 /// Returns true when a stale mobile one-shot Shift state should be released
 /// by replaying a tracked Shift key-down as a synthesized key-up.
@@ -36,3 +44,147 @@ bool shouldReleaseStaleMobileShift({
   }
   return true;
 }
+
+/// Applies the terminal Ctrl/Alt one-shot modifiers to a single input payload.
+///
+String applyTerminalInputModifiers(
+  String data, {
+  required bool ctrlLocked,
+  required bool altLocked,
+}) {
+  var result = data;
+  if (ctrlLocked) {
+    result = _applyTerminalCtrlModifier(result);
+  }
+  if (altLocked) {
+    result = '\x1B$result';
+  }
+  return result;
+}
+
+/// Builds the exact payload xterm sends for paste, without applying modifiers.
+String terminalPastePayload(String text, {required bool bracketedPasteMode}) {
+  if (!bracketedPasteMode) {
+    return text;
+  }
+  return '\x1B[200~$text\x1B[201~';
+}
+
+/// Returns whether one-shot Ctrl/Alt may transform and consume this input.
+///
+/// xterm emits terminal control keys as either one control byte or a longer
+/// escape sequence. Neither form is ordinary text input, so a pending modifier
+/// must survive until the user enters a printable character.
+bool shouldApplyTerminalInputModifiers(String data) {
+  if (data.characters.length != 1) return false;
+  final codeUnit = data.codeUnitAt(0);
+  return codeUnit >= 0x20 && codeUnit != 0x7F;
+}
+
+/// Builds the payload sent to the remote terminal for keyboard and paste input.
+///
+/// Keyboard input keeps the mobile Enter workaround and one-shot Ctrl/Alt
+/// mapping. Paste input deliberately bypasses both transformations so even a
+/// one-character clipboard payload is preserved exactly.
+String prepareTerminalInputPayload(
+  String data, {
+  required TerminalInputSource source,
+  required bool isMobileOrWebMobile,
+  required bool bracketedPasteMode,
+  required bool ctrlLocked,
+  required bool altLocked,
+}) {
+  if (source == TerminalInputSource.paste) {
+    return terminalPastePayload(
+      data,
+      bracketedPasteMode: bracketedPasteMode,
+    );
+  }
+
+  var result = data;
+  if (isMobileOrWebMobile && result == '\n') {
+    result = '\r';
+  }
+  if ((ctrlLocked || altLocked) && shouldApplyTerminalInputModifiers(result)) {
+    result = applyTerminalInputModifiers(
+      result,
+      ctrlLocked: ctrlLocked,
+      altLocked: altLocked,
+    );
+  }
+  return result;
+}
+
+/// Returns true when a hardware paste shortcut must bypass keyboard modifiers.
+///
+/// xterm already handles hardware Ctrl/Cmd+V correctly in the common case. Only
+/// intercept while a virtual Ctrl/Alt lock is active, because xterm can emit a
+/// one-character paste as normal text when bracketed paste mode is disabled.
+bool shouldHandleTerminalPasteShortcut({
+  required LogicalKeyboardKey logicalKey,
+  required bool isKeyDown,
+  required bool isKeyRepeat,
+  required bool controlPressed,
+  required bool metaPressed,
+  required bool altPressed,
+  required bool shiftPressed,
+  required bool modifierLockActive,
+}) {
+  if (!modifierLockActive) return false;
+  if (!isKeyDown && !isKeyRepeat) return false;
+  if (logicalKey != LogicalKeyboardKey.keyV) return false;
+  if (altPressed || shiftPressed) return false;
+  return controlPressed != metaPressed;
+}
+
+/// Returns true when collapsing Row3 should also clear hidden modifier state.
+bool shouldClearTerminalModifiersWhenRow3Collapses({
+  required bool wasExpanded,
+  required bool willExpand,
+  required bool ctrlLocked,
+  required bool altLocked,
+}) {
+  return wasExpanded && !willExpand && (ctrlLocked || altLocked);
+}
+
+String _applyTerminalCtrlModifier(String data) {
+  // Ctrl mappings are defined only for ASCII scalars. A visible character can
+  // be multiple scalars (for example, a decomposed accent), so leave those
+  // graphemes untouched instead of rewriting only their ASCII base letter.
+  final graphemes = data.characters.toList(growable: false);
+  if (graphemes.length != 1) {
+    return data;
+  }
+
+  final runes = graphemes.single.runes.toList(growable: false);
+  if (runes.length != 1) {
+    return data;
+  }
+
+  final code = runes.single;
+  if (code >= 0x61 && code <= 0x7A) {
+    return String.fromCharCode(code - 0x60);
+  }
+  if (code >= 0x41 && code <= 0x5A) {
+    return String.fromCharCode(code - 0x40);
+  }
+  if (code == 0x20) {
+    return String.fromCharCode(0);
+  }
+  if (code == 0x5B) {
+    return String.fromCharCode(27);
+  }
+  if (code == 0x5C) {
+    return String.fromCharCode(28);
+  }
+  if (code == 0x5D) {
+    return String.fromCharCode(29);
+  }
+  if (code == 0x5E) {
+    return String.fromCharCode(30);
+  }
+  if (code == 0x5F || code == 0x2F) {
+    return String.fromCharCode(31);
+  }
+  return data;
+}

flutter/lib/models/terminal_model.dart

@@ -7,6 +7,7 @@ import 'package:flutter_hbb/consts.dart';
 import 'package:flutter_hbb/main.dart';
 import 'package:xterm/xterm.dart';
 
+import 'input_modifier_utils.dart';
 import 'model.dart';
 import 'platform_model.dart';
 
@@ -22,7 +23,25 @@ class TerminalModel with ChangeNotifier {
 
   bool _disposed = false;
 
+  /// Callback to check whether Ctrl modifier lock is currently active.
+  /// When active, keyboard input is mapped to control codes (e.g. 'b' → \x02).
+  bool Function()? isCtrlLocked;
+
+  /// Callback to clear Ctrl lock after a key is pressed (one-shot mode).
+  void Function()? clearCtrlLock;
+
+  /// Callback to check whether Alt modifier lock is currently active.
+  bool Function()? isAltLocked;
+
+  /// Callback to clear Alt lock after a key is pressed (one-shot mode).
+  void Function()? clearAltLock;
+
   final _inputBuffer = <String>[];
+
+  /// Exposes buffered input only for lifecycle regression tests.
+  @visibleForTesting
+  int get debugBufferedInputCount => _inputBuffer.length;
+
   // Buffer for output data received before terminal view has valid dimensions.
   // This prevents NaN errors when writing to terminal before layout is complete.
   final _pendingOutputChunks = <String>[];
@@ -42,6 +61,10 @@ class TerminalModel with ChangeNotifier {
   VoidCallback? onClosed;
 
   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.
+    if (_disposed) return;
+
     // Soft keyboards (notably iOS) emit '\n' when Enter is pressed, while a
     // real keyboard's Enter sends '\r'. Some Android keyboards also emit '\n'.
     // - Peer Windows: '\r' works, '\n' is just a newline.
@@ -49,13 +72,44 @@ class TerminalModel with ChangeNotifier {
     //   (readline, prompt_toolkit, vim, TUI frameworks) expect '\r'.
     // - Peer macOS: same as Linux, raw-mode apps expect '\r'
     //   (https://github.com/rustdesk/rustdesk/issues/14907).
-    // So on mobile / web-mobile, always normalize a lone '\n' to '\r'.
-    // We deliberately do not touch multi-character payloads (e.g. pasted text)
-    // so embedded newlines in pasted content are preserved.
-    final isMobileOrWebMobile = (isMobile || (isWeb && !isWebDesktop));
-    if (isMobileOrWebMobile && data == '\n') {
-      data = '\r';
+    // So on mobile / web-mobile, normalize the original lone '\n' to '\r'
+    // before modifier mappings. This keeps Ctrl+J mapped to LF instead of
+    // having the generated control code rewritten to CR afterward.
+    // Multi-character keyboard payloads, such as terminal escape sequences,
+    // remain unchanged. Paste input follows a separate preprocessing path.
+    final ctrlLocked = isCtrlLocked?.call() ?? false;
+    final altLocked = isAltLocked?.call() ?? false;
+    final modifiersActive = ctrlLocked || altLocked;
+    // Use the same predicate for transformation and consumption. Control keys
+    // and escape sequences must not silently consume a pending one-shot lock.
+    final shouldConsumeModifiers =
+        modifiersActive && shouldApplyTerminalInputModifiers(data);
+    data = prepareTerminalInputPayload(
+      data,
+      // IME soft-keyboard paste prompts currently arrive from xterm as normal
+      // text input with no paste-origin metadata. Keep them on the keyboard path;
+      // clipboard-content heuristics can misclassify ordinary typing.
+      source: TerminalInputSource.keyboard,
+      isMobileOrWebMobile: isMobile || (isWeb && !isWebDesktop),
+      bracketedPasteMode: terminal.bracketedPasteMode,
+      ctrlLocked: ctrlLocked,
+      altLocked: altLocked,
+    );
+    if (shouldConsumeModifiers) {
+      if (ctrlLocked) clearCtrlLock?.call();
+      if (altLocked) clearAltLock?.call();
     }
+    return _sendInputPayload(data);
+  }
+
+  /// Sends an already prepared payload without applying keyboard semantics.
+  /// Both normal input and paste use this transport path after their source-
+  /// specific preprocessing has completed.
+  Future<void> _sendInputPayload(String data) async {
+    // Clipboard reads and native sends may complete after the terminal page has
+    // closed. Never send or re-buffer input once this model is disposed.
+    if (_disposed) return;
+
     if (_terminalOpened) {
       // Send user input to remote terminal
       try {
@@ -176,6 +230,18 @@ class TerminalModel with ChangeNotifier {
     return _handleInput(data);
   }
 
+  Future<void> pasteText(String data) async {
+    final payload = prepareTerminalInputPayload(
+      data,
+      source: TerminalInputSource.paste,
+      isMobileOrWebMobile: false,
+      bracketedPasteMode: terminal.bracketedPasteMode,
+      ctrlLocked: false,
+      altLocked: false,
+    );
+    return _sendInputPayload(payload);
+  }
+
   Future<void> closeTerminal() async {
     if (_terminalOpened) {
       try {
@@ -516,6 +582,14 @@ class TerminalModel with ChangeNotifier {
   void dispose() {
     if (_disposed) return;
     _disposed = true;
+    terminal.onOutput = null;
+    terminal.onResize = null;
+    isCtrlLocked = null;
+    clearCtrlLock = null;
+    isAltLocked = null;
+    clearAltLock = null;
+    onResizeExternal = null;
+    onClosed = null;
     // Clear buffers to free memory
     _inputBuffer.clear();
     _pendingOutputChunks.clear();