feat(web): add fallback paste mechanism for mobile terminal

- Add hidden textarea as fallback when Clipboard API unavailable
- Improve error handling: throw exceptions instead of silent failures
- Show user-friendly toast prompts guiding manual paste operation
- Add translations for paste error/fallback messages (en/zh)
- Automatically send pasted text to terminal from textarea input
- Handle non-HTTPS, older browsers, and permission restrictions gracefully

Author: pallyoung

packages/web/src/features/terminal-panel/uploads/use-paste-drop-upload.ts

@@ -121,13 +121,7 @@ export function usePasteDropUpload(opts: Options): PasteDropUploadActions {
 
     const clipboard = navigator.clipboard;
     if (!clipboard) {
-      pushToast({
-        kind: "error",
-        title: "Paste failed",
-        body: "Clipboard API not available",
-        duration: 3_000,
-      });
-      return;
+      throw new Error("Clipboard API not available");
     }
 
     try {
@@ -160,13 +154,7 @@ export function usePasteDropUpload(opts: Options): PasteDropUploadActions {
     try {
       const readText = clipboard.readText?.bind(clipboard);
       if (!readText) {
-        pushToast({
-          kind: "error",
-          title: "Paste failed",
-          body: "Clipboard text read not available",
-          duration: 3_000,
-        });
-        return;
+        throw new Error("Clipboard text read not available");
       }
 
       const text = await readText();
@@ -181,13 +169,14 @@ export function usePasteDropUpload(opts: Options): PasteDropUploadActions {
       }
 
       await handleText(text);
-    } catch (_error) {
+    } catch (error) {
       pushToast({
         kind: "error",
         title: "Paste failed",
         body: "Could not read from clipboard. Please check permissions.",
         duration: 3_000,
       });
+      throw error;
     }
   }, [enabled, handleFiles, handleText, pushToast]);
 

packages/web/src/features/terminal-panel/views/shared/xterm-host.tsx

@@ -2168,9 +2168,41 @@ export function XtermHost({
 
   const fileInputRef = useRef<HTMLInputElement | null>(null);
 
-  const handleMobilePaste = useCallback(() => {
-    void handleClipboardPaste();
-  }, [handleClipboardPaste]);
+  const pasteTextareaRef = useRef<HTMLTextAreaElement | null>(null);
+
+  const handleMobilePaste = useCallback(async () => {
+    // Try modern Clipboard API first
+    if (navigator.clipboard) {
+      try {
+        await handleClipboardPaste();
+        return;
+      } catch (error) {
+        console.debug("Clipboard API failed, trying fallback:", error);
+      }
+    }
+
+    // Fallback: use hidden textarea for manual paste
+    const textarea = pasteTextareaRef.current;
+    if (!textarea) {
+      pushToast({
+        kind: "error",
+        title: t("terminal.mobile_paste_failed_title"),
+        body: t("terminal.mobile_paste_failed_body"),
+      });
+      return;
+    }
+
+    textarea.value = "";
+    textarea.focus();
+    textarea.select();
+
+    pushToast({
+      kind: "info",
+      title: t("terminal.mobile_paste_manual_title"),
+      body: t("terminal.mobile_paste_manual_body"),
+      duration: 3_000,
+    });
+  }, [handleClipboardPaste, pushToast, t]);
 
   const handleMobileUpload = useCallback(() => {
     fileInputRef.current?.click();
@@ -2245,6 +2277,17 @@ export function XtermHost({
           void handleFileInputChange(event);
         }}
       />
+      <textarea
+        ref={pasteTextareaRef}
+        hidden
+        onChange={async (event) => {
+          const text = event.currentTarget.value;
+          if (text) {
+            await sendTextToTerminal(text);
+            event.currentTarget.value = "";
+          }
+        }}
+      />
       <div
         ref={containerRef}
         className="xterm-host"

packages/web/src/locales/en.json

@@ -262,6 +262,10 @@
     "copied_current_line": "Copied current line",
     "mobile_copy_current_line_failed_title": "Current line copy failed",
     "mobile_copy_current_line_failed_body": "Try long-pressing the current line again",
+    "mobile_paste_failed_title": "Paste failed",
+    "mobile_paste_failed_body": "Could not paste from clipboard",
+    "mobile_paste_manual_title": "Paste",
+    "mobile_paste_manual_body": "Please paste your text in the text area",
     "hide": "Hide Terminal",
     "show": "Show Terminal",
     "selector": {

packages/web/src/locales/zh.json

@@ -262,6 +262,10 @@
     "copied_current_line": "已复制当前行",
     "mobile_copy_current_line_failed_title": "当前行复制失败",
     "mobile_copy_current_line_failed_body": "请重试长按当前行",
+    "mobile_paste_failed_title": "粘贴失败",
+    "mobile_paste_failed_body": "无法从剪贴板粘贴",
+    "mobile_paste_manual_title": "粘贴",
+    "mobile_paste_manual_body": "请在文本框中粘贴您的文本",
     "hide": "隐藏终端",
     "show": "显示终端",
     "selector": {