forwardemail 0.14.20 → 0.14.22

package/README.md

@@ -17,6 +17,7 @@ forwardemail
   - [Commands and options](#commands-and-options)
   - [Keys and mouse](#keys-and-mouse)
   - [Plain text](#plain-text)
+  - [Attachments](#attachments)
   - [Notifications](#notifications)
   - [Environment variables](#environment-variables)
   - [Where data is stored](#where-data-is-stored)
@@ -140,17 +141,22 @@ Click a hint to press its key. Press `?` for every shortcut. To change one, choo
 
 What you type right after a new-message, reply or forward shortcut (Ctrl+N, `r`, `a`, `f`, or the keys you gave them) goes into the new message, even before its window has appeared.
 
-| Key                 | Action                                                                           |
-| :------------------ | :------------------------------------------------------------------------------- |
-| `Tab` / `Shift+Tab` | Move between controls. The focused control is highlighted.                       |
-| `Enter` / `Space`   | Activate the focused button or link.                                             |
-| `↑` / `↓`           | Move through the message list.                                                   |
-| `Esc`               | Close a dialog or menu; otherwise go back (from a message, a contact, settings). |
-| `Ctrl+N`            | Compose a new message.                                                           |
-| `r` / `a` / `f`     | Reply, reply all, forward.                                                       |
-| `e` / `s` / `Del`   | Archive, star, delete.                                                           |
-| `?`                 | Show every keyboard shortcut.                                                    |
-| `Ctrl+C`            | Quit and give the terminal back.                                                 |
+| Key                   | Action                                                                           |
+| :-------------------- | :------------------------------------------------------------------------------- |
+| `Tab` / `Shift+Tab`   | Move between controls, starting from where you clicked. Focus is highlighted.    |
+| `Enter` / `Space`     | Activate the focused button or link.                                             |
+| `↑` / `↓`             | Open the next or previous message, counting from the focused row in the list.    |
+| `Shift+↓` / `Shift+↑` | Check messages below or above, for the bulk actions (archive, delete, …).        |
+| `x`                   | Check or uncheck the open or focused message.                                    |
+| `Esc`                 | Close a dialog or menu; otherwise go back (from a message, a contact, settings). |
+| `Ctrl+N`              | Compose a new message.                                                           |
+| `Ctrl+O`              | Attach a file to the message you are writing (see [Attachments](#attachments)).  |
+| `r` / `a` / `f`       | Reply, reply all, forward.                                                       |
+| `e` / `s` / `Del`     | Archive, star, delete.                                                           |
+| `?`                   | Show every keyboard shortcut.                                                    |
+| `Ctrl+C`              | Copy the selected text; with nothing selected, quit (after asking).              |
+
+Opening a message moves the keyboard into it, so `Tab` goes through its buttons and addresses. Going back to the list puts the focus on that message's row.
 
 `forwardemail` uses the terminal's alternate screen, as `vim` and `less` do. The wheel scrolls the app, not your shell's history, and quitting puts your shell's screen back as it was.
 
@@ -158,7 +164,9 @@ A scroll bar on the right edge of the message list, a message, the compose windo
 
 Clicking and scrolling with the wheel work with the mouse in any terminal that reports mouse events. That includes most modern terminals: iTerm2, Terminal.app, GNOME Terminal, Konsole, kitty, WezTerm, Alacritty, foot and Windows Terminal. A terminal of 120 columns or more shows the full desktop layout. At 80 columns or fewer (the webmail's 640 px phone breakpoint), the folder list moves behind the `≡` menu, as on a phone.
 
-Drag over text, in a message or anywhere else, to select it. Releasing the button copies it to your clipboard, and the bottom row says **Copied**. The copy goes through the terminal's clipboard sequence (OSC 52), so it also works over SSH. In tmux, add `set -g set-clipboard on`. iTerm2 asks first: allow it under **Settings › General › Selection › Applications in terminal may access clipboard**. To use your terminal's own selection instead, hold its modifier while you drag: Option in iTerm2, Fn in Terminal.app, Shift in most others.
+In the message list, Shift+click on a checkbox checks the messages between it and the last one clicked, as in the browser, in a terminal that passes Shift+click on to the app; most keep it for their own text selection, so `Shift+↓`, `Shift+↑` and `x` do the same from the keyboard.
+
+Drag over text, in a message or anywhere else, to select it, then press `Ctrl+C` to copy it. The bottom row shows **Ctrl+C Copy** while text is selected. A click on an address in an open message copies the address. A copy goes to your clipboard two ways: through the system's clipboard program (`pbcopy` on macOS, PowerShell or `clip.exe` on Windows and in WSL, `wl-copy` under Wayland, `xclip` or `xsel` under X11), and through the terminal's clipboard sequence (OSC 52), the way that works over SSH. The app says **Copied** when the text got there. It says the copy failed when a clipboard program failed, or when none is installed and the terminal ignores OSC 52 (GNOME Terminal and the other VTE terminals, Terminal.app, the Linux console). On Linux, install `wl-clipboard` or `xclip` for copies in those terminals. Over SSH, the terminal has to accept OSC 52: in tmux, add `set -g set-clipboard on` (or `set -g allow-passthrough on`); iTerm2 asks first, allow it under **Settings › General › Selection › Applications in terminal may access clipboard**. To use your terminal's own selection instead, hold its modifier while you drag: Option in iTerm2, Fn in Terminal.app, Shift in most others.
 
 With the pointer on a button, the bottom row shows the button's name. Ghostty, kitty, WezTerm and foot also change the pointer to a hand over links and buttons and to an I-beam over text fields. `FORWARDEMAIL_POINTER=1` asks other terminals to do the same, and `FORWARDEMAIL_POINTER=0` stops it.
 
@@ -168,6 +176,30 @@ Links in messages, and links to other sites, open in your default browser. Files
 
 Messages are shown, and new messages written, as plain text by default in the terminal. A reply quotes the original with `>` in front of each line. The **T** button next to **Save draft** in the compose window switches that message to rich text, with the formatting toolbar, and back. To change the default, use **Settings › Appearance › Use plain text by default** and **Settings › Privacy & Security › View emails as plain text**. The browser, desktop and mobile apps keep rich text as their default.
 
+### Attachments
+
+To attach files, choose **⌇** (Attach file) in the compose window or press `Ctrl+O`. The bottom row lists `Ctrl+O` where there is room; at 80 columns it leaves it out to keep `Ctrl+C Quit`. A file dialog opens:
+
+| System        | Dialog                                                                                                                                         |
+| :------------ | :--------------------------------------------------------------------------------------------------------------------------------------------- |
+| macOS         | The system's Open dialog, through `osascript`.                                                                                                 |
+| Linux and BSD | `zenity` or `kdialog`, when there is a display. KDE desktops try `kdialog` first. Install either one (packages `zenity`, `kdialog`) to use it. |
+| Windows       | The system's Open dialog, through PowerShell.                                                                                                  |
+| WSL           | The Windows Open dialog, through PowerShell; the files come back as `/mnt/c/…` paths. With WSLg, `zenity` or `kdialog` is the fallback.        |
+
+Over SSH, and on Linux without a display, the bottom row asks for the file's path instead:
+
+```text
+ File to attach: ~/Documents/rep
+ Tab Complete   Enter Attach   Esc Cancel
+```
+
+Tab completes a name as a shell does and lists the names when several match. A relative path starts in the directory you ran `forwardemail` from. Enter attaches the file. Esc, or a click elsewhere, cancels. Over SSH with X forwarding (`ssh -X`), Linux uses the dialog on your display. `FORWARDEMAIL_FILE_PICKER=terminal` always asks on the bottom row. While a dialog is open, Esc in the terminal closes it.
+
+You can also drag files from your file manager and drop them on the terminal window while the compose window is open. A terminal turns a drop into the files' paths, pasted as text. The client reads those paths and attaches the files in place of the text. It understands the ways terminals write them: backslash escapes (macOS Terminal, iTerm2, Ghostty), quotes (GNOME Terminal, WezTerm, Windows Terminal), `file://` links with `%20` for spaces, a path per line, and Windows paths under WSL. A paste in the To, Cc, Bcc or Subject field stays text, and so does a pasted path to a file that does not exist. To put the path of an existing file into the message, type it. The terminal has to mark the drop as a paste (bracketed paste), as current terminals do; a terminal that types the path out instead puts it into the message as text.
+
+The client skips folders, and files that would take the message's attachments past 37.5 MB, counting the ones already on it: the server takes messages up to 50 MB, and encoding makes attachments a third larger. Removing an attachment makes room again. The bottom row says what the client attached and what it skipped. Each attachment shows below the message with its size, and its **✕** removes it.
+
 ### Notifications
 
 New mail that arrives while the terminal is in the background shows as a desktop notification, as it does in a browser tab you are not looking at. While you are using the terminal, it shows inside the app instead. Calendar reminders work the same way.
@@ -186,16 +218,17 @@ Notifications are off over SSH, since they would appear on the remote computer,
 
 ### Environment variables
 
-| Variable                       | Effect                                                                               |
-| :----------------------------- | :----------------------------------------------------------------------------------- |
-| `FORWARDEMAIL_HOME`            | Same as `--data-dir`: the directory for settings and the session (see below).        |
-| `FORWARDEMAIL_API_URL`         | Same as `--api`.                                                                     |
-| `FORWARDEMAIL_NO_UPDATE_CHECK` | Same as `--no-update-check`.                                                         |
-| `FORWARDEMAIL_NO_HINTS`        | Same as `--no-hints`.                                                                |
-| `FORWARDEMAIL_NOTIFICATIONS`   | `0` is the same as `--no-notifications`. `1` shows them over SSH too.                |
-| `FORWARDEMAIL_POINTER`         | `1` asks any terminal to change the pointer shape, `0` none (see above).             |
-| `FORWARDEMAIL_DOWNLOADS`       | Where saved files go, instead of `~/Downloads` (or your home directory without one). |
-| `FORWARDEMAIL_DEBUG`           | Writes the app's console output to `forwardemail.log` in the data directory.         |
+| Variable                       | Effect                                                                                |
+| :----------------------------- | :------------------------------------------------------------------------------------ |
+| `FORWARDEMAIL_HOME`            | Same as `--data-dir`: the directory for settings and the session (see below).         |
+| `FORWARDEMAIL_API_URL`         | Same as `--api`.                                                                      |
+| `FORWARDEMAIL_NO_UPDATE_CHECK` | Same as `--no-update-check`.                                                          |
+| `FORWARDEMAIL_NO_HINTS`        | Same as `--no-hints`.                                                                 |
+| `FORWARDEMAIL_NOTIFICATIONS`   | `0` is the same as `--no-notifications`. `1` shows them over SSH too.                 |
+| `FORWARDEMAIL_POINTER`         | `1` asks any terminal to change the pointer shape, `0` none (see above).              |
+| `FORWARDEMAIL_DOWNLOADS`       | Where saved files go, instead of `~/Downloads` (or your home directory without one).  |
+| `FORWARDEMAIL_FILE_PICKER`     | `terminal` asks for a file's path on the bottom row instead of opening a file dialog. |
+| `FORWARDEMAIL_DEBUG`           | Writes the app's console output to `forwardemail.log` in the data directory.          |
 
 ### Where data is stored
 
@@ -290,6 +323,7 @@ The terminal client runs the webmail's own code, so features behave the same way
 - **Fonts and font sizes** are the terminal's. Headings stand out by weight and color, not size.
 - **Passkeys** (WebAuthn) need a browser or the desktop app. To use App Lock in the terminal, unlock it with its PIN.
 - **Push notifications and the service worker** are unavailable. New mail arrives over the WebSocket connection while the app is open, and shows as a [desktop notification](#notifications) when the terminal is in the background.
+- **Drag and drop** reaches the terminal as pasted file paths, which the compose window turns into attachments (see [Attachments](#attachments)).
 - **Hover tooltips** appear in the bottom row rather than over the page, where they would cover the controls around them.
 - **Transparency and animation** are flattened: translucent colors are blended with the page background, and transitions jump to their end.
 - **Esc followed by a key** in quick succession counts as two presses, not as Alt plus the key (some terminals send Alt that way). The exceptions are Alt+Backspace and Alt+B/F/D, which keep their word-editing meaning in text fields. The webmail has no other Alt shortcuts.
@@ -326,9 +360,10 @@ The webmail is built a second time for Node.js, and the result is a single Commo
    - `history` and `location` ([`src/cli/history.ts`](../src/cli/history.ts))
    - sandboxed message frames ([`src/cli/frames.ts`](../src/cli/frames.ts))
    - downloads and outside links ([`src/cli/links.ts`](../src/cli/links.ts))
+   - file inputs, file dialogs and dropped files ([`src/cli/attachments.ts`](../src/cli/attachments.ts)), and `FileReader` ([`src/cli/file-reader.ts`](../src/cli/file-reader.ts))
    - geometry scaled to the virtual pixel grid ([`src/cli/viewport.ts`](../src/cli/viewport.ts))
 
-The application code under `src/` is untouched. Everything specific to the terminal lives in `src/cli/`, and the browser and desktop builds do not include it.
+The application code under `src/` runs as it is; the one addition for the terminal is the compose window's `data-attachment-bytes` attribute, which the attachment size limit reads. Everything specific to the terminal lives in `src/cli/`, and the browser and desktop builds do not include it.
 
 The standalone executables are [Node.js single executable applications](https://nodejs.org/api/single-executable-applications.html): the bundle is injected into a copy of the `node` binary by [`scripts/build-sea.mjs`](../scripts/build-sea.mjs).