copyhub-cli 1.0.5 → 1.0.8

package/.env.example

@@ -16,7 +16,8 @@ COPYHUB_GOOGLE_CLIENT_ID=
 COPYHUB_GOOGLE_CLIENT_SECRET=
 COPYHUB_OAUTH_REDIRECT_PORT=19999
 
-# Overlay accelerator (optional): if set here it OVERRIDES the value saved after copyhub login (config overlayAccelerator).
+# Overlay accelerator (optional): overrides config. Default app-wide is Control+Shift+H (⌃/Ctrl + Shift + H).
+# Example Mac ⌘ shortcut: COPYHUB_OVERLAY_ACCELERATOR=CommandOrControl+Shift+H
 COPYHUB_OVERLAY_ACCELERATOR=
 
 # Set to 1 to NOT show the window when overlay starts (open via shortcut / tray only).

package/README.md

@@ -1,228 +1,282 @@
 # CopyHub
 
-CopyHub watches your **clipboard**, keeps a **local history** under `~/.copyhub/history.jsonl`, optionally syncs copies to **Google Sheets** (one tab per day), and shows an **Electron overlay** so you can browse recent clips quickly.
+CopyHub theo dõi **clipboard**, lưu **lịch sử cục bộ** (`~/.copyhub/history.jsonl`), tùy chọn đồng bộ lên **Google Sheets** (một tab mỗi ngày), và mở **overlay Electron** để xem và chọn bản copy gần đây.  
+English summary: watches clipboard, local JSONL history, optional daily Google Sheets tabs, floating history overlay.
 
-Runs on **Windows**, **macOS**, and **Linux**.
+Chạy trên **Windows**, **macOS**, và **Linux**.
 
-## Requirements
+---
 
-- **Node.js** ≥ 18
-- A **Google Cloud** project with:
-  - **Google Sheets API** enabled for the *same* project as your OAuth client
-  - **OAuth 2.0 Client** (Desktop app type works well for localhost redirect)
+## Mục lục / Table of contents
 
-## Installation
+Các mục `##` bên dưới theo thứ tự: **Tính năng** · **Yêu cầu** · **Cài đặt** · **File `.env`** · **Google Cloud & OAuth** · **OAuth config vs env** · **Chạy lần đầu** · **Lệnh CLI** · **Biến môi trường** · **Thư mục dữ liệu** · **Google Sheets** · **Overlay** · **Clipboard & lịch sử** · **Nâng cấp** · **Xử lý sự cố** · **Bảo mật** · **Giấy phép**.
 
-### Install globally (npm)
+---
 
-After the package is published to npm:
+## Tính năng / Features
 
-```bash
-npm install -g copyhub-cli
-```
+- Theo dõi clipboard theo chu kỳ (có thể chỉnh `COPYHUB_POLL_MS`).
+- Không lưu hai lần liên tiếp **cùng một nội dung** vào `history.jsonl` / Sheet.
+- Ghi Sheet theo tab **`COPYHUB-YYYY-MM-DD`** (timezone máy).
+- Overlay: phân trang lịch sử, đồng bộ Sheet theo từng bước (không tải hết một lúc), gợi ý khi đang load Sheet.
+
+---
+
+## Yêu cầu / Requirements
 
-Then run `copyhub` from any directory (ensure Node.js ≥ 18 is on your `PATH`).
+- **Node.js** ≥ 18  
+- Một **Google Cloud project** có:
+  - **Google Sheets API** bật **trên cùng project** với OAuth client  
+  - OAuth client kiểu **Web application** và redirect URI đúng (xem dưới)
 
-On Linux/macOS you may need elevated permissions or an npm prefix configured for your user; see [npm docs on global installs](https://docs.npmjs.com/cli/v10/commands/npm-install#global-installation).
+---
 
-### From source (this repository)
+## Cài đặt / Installation
 
-From the repository root:
+### Cài global (npm)
 
 ```bash
-npm install
+npm install -g copyhub-cli
 ```
 
-Register the CLI on your machine:
+Đảm bảo `node` và `copyhub` có trong `PATH`. Linux/macOS có thể cần cấu hình prefix npm cho user — xem [npm global installation](https://docs.npmjs.com/cli/v10/commands/npm-install#global-installation).
+
+### Từ mã nguồn (repo)
 
 ```bash
+npm install
 npm link
 ```
 
-Or run without linking:
+Hoặc không link:
 
 ```bash
 node src/cli.js <command>
 ```
 
-## Updating
+---
 
-Your settings (`~/.copyhub/config.json`, tokens, history) are kept when you upgrade the CLI.
+## File `.env` và thứ tự đọc / Environment files
 
-**Recommended:** stop the background daemon before upgrading so Electron can reinstall cleanly; after upgrading start again:
+CLI và Electron overlay gọi `loadCopyhubEnv()`: đọc lần lượt các file `.env`, parse rồi **gộp một object** — **file sau ghi đè key trùng** với file trước. Sau đó mỗi key chỉ được đưa vào `process.env` nếu biến đó **chưa tồn tại** trong môi trường tiến trình (shell đã `export` trước khi chạy Node thì luôn thắng).
 
-```bash
-copyhub stop
-```
+Thứ tự file:
 
-*(Skip `stop` if you only run `--foreground` or `overlay` and nothing is in the background.)*
+1. `<package>/.env` (thư mục cài package / repo khi dev)  
+2. `~/.copyhub/.env`  
+3. `./.env` của **thư mục làm việc hiện tại** (`cwd`)
 
-### Global install (`npm install -g copyhub-cli`)
+Nhờ đó `npm install -g` vẫn đọc được biến khi bạn đặt `~/.copyhub/.env`, không phụ thuộc cwd.
 
-Check what npm considers latest vs what you have:
+Tham khảo mẫu: `.env.example`.
 
-```bash
-npm view copyhub-cli version
-```
+---
 
-Upgrade to the latest published release:
+## Google Cloud & OAuth
 
-```bash
-npm install -g copyhub-cli@latest
-```
+1. Bật **[Google Sheets API](https://console.cloud.google.com/apis/library/sheets.googleapis.com)** cho project.  
+2. **Credentials** → **Create credentials** → **OAuth client ID** → kiểu **Web application**.  
+3. **Authorized redirect URIs** — thêm **chính xác** (CopyHub dùng `127.0.0.1`, không dùng `localhost` trong redirect mặc định):
 
-Alternatively:
+   ```text
+   http://127.0.0.1:19999/oauth2callback
+   ```
 
-```bash
-npm update -g copyhub-cli
-```
+   Nếu đổi port (`COPYHUB_OAUTH_REDIRECT_PORT` hoặc `redirectPort` trong config), URI trong Console phải khớp port đó.
 
-Restart CopyHub:
+4. **Không** trộn Client ID trong env với Secret trong file (CopyHub đã chặn trộn nửa cặp). Ưu tiên credentials — xem mục sau.
 
-```bash
-copyhub start
-```
+### Cách đưa Client ID / Secret vào CopyHub
+
+| Cách | Ghi chú |
+|------|---------|
+| **`copyhub login`** | Khuyến nghị lần đầu: wizard localhost nhập ID/Secret → lưu `config.json` → Google đăng nhập → trang nhập Spreadsheet ID / phím tắt. |
+| **`copyhub config --client-id … --client-secret …`** | Ghi thẳng `config.json`. |
+| **`.env`** hoặc shell | Chỉ dùng khi **chưa** có đủ cặp trong `config.json`, hoặc bạn cố ý chỉ dùng env (không ghi OAuth vào config). |
 
-To see the installed package version: `npm list -g copyhub-cli --depth=0`.
+Trên wizard (Mac/Safari): nên **Download JSON** từ Console và paste `client_id` / `client_secret`; xóa sạch ô trước khi dán để tránh Keychain điền nhầm secret cũ.
 
-### From source
+---
 
-Pull latest commits and reinstall modules:
+## OAuth: config vs env (quan trọng)
+
+- Nếu **`~/.copyhub/config.json` có đủ** `clientId` **và** `clientSecret` → CopyHub **luôn dùng cặp trong file** cho OAuth; **`COPYHUB_GOOGLE_*` trong env/.env bị bỏ qua** cho hai field đó.  
+- Nếu file **không** có đủ cặp → dùng **`COPYHUB_GOOGLE_CLIENT_ID`** + **`COPYHUB_GOOGLE_CLIENT_SECRET`** từ env (đã merge từ `.env`).  
+- Không bao giờ ghép ID env với Secret file (hoặc ngược lại).
+
+Giá trị ID/Secret được **sanitize** khi đọc/ghi (BOM, CRLF, NBSP, ký tự zero-width, ngoặc dư thừa quanh chuỗi).
+
+Kiểm tra nguồn đang dùng:
 
 ```bash
-copyhub stop
-git pull
-npm install
+copyhub status
 ```
 
-If you previously ran **`npm link`**, linking stays tied to this folder — after `npm install` you usually **do not** need to link again unless npm warns otherwise:
+---
+
+## Chạy lần đầu / First run
 
 ```bash
-npm link
+copyhub login
 ```
 
-Then:
+1. Nếu chưa có OAuth trong config/env đủ cặp → trình duyệt mở **`http://127.0.0.1:<port>/credentials`** để nhập Client ID / Secret.  
+2. Sau đó đăng nhập Google; callback **`/oauth2callback`**.  
+3. Trang setup: **Spreadsheet ID** (từ URL `…/d/<ID>/edit`), **platform**, **phím tắt overlay** (tuỳ chọn).
+
+Chạy daemon (clipboard + Sheet + overlay mặc định):
 
 ```bash
 copyhub start
 ```
 
-## Google Cloud setup
+Terminal có thể đóng; tiến trình chạy nền. Xem `copyhub list`, dừng `copyhub stop`.
 
-1. Enable **[Google Sheets API](https://console.cloud.google.com/apis/library/sheets.googleapis.com)** on your OAuth project.
-2. Create **OAuth 2.0 credentials** and add this **Authorized redirect URI** (adjust the port if you change it):
+Chạy gắn terminal (Ctrl+C tắt hết):
 
-   ```text
-   http://127.0.0.1:19999/oauth2callback
-   ```
+```bash
+copyhub start --foreground
+```
 
-3. Provide OAuth credentials in **any one** of these ways:
+---
 
-   - **Recommended for first setup:** run **`copyhub login`** with no secrets configured — your browser opens a **localhost wizard** where you paste **Client ID** and **Client secret** (the same values as `COPYHUB_GOOGLE_CLIENT_ID` / `COPYHUB_GOOGLE_CLIENT_SECRET`); they are stored in `~/.copyhub/config.json`.
+## Lệnh CLI / CLI commands
 
-   - Copy `.env.example` to **`~/.copyhub/.env`** and/or a `.env` in your project folder and set `COPYHUB_GOOGLE_CLIENT_ID`, `COPYHUB_GOOGLE_CLIENT_SECRET`, and optionally `COPYHUB_OAUTH_REDIRECT_PORT` (default **19999**). This works even with **`npm install -g`** when your shell is not in the repo directory.
+| Lệnh | Mô tả |
+|------|--------|
+| `copyhub config --client-id ID --client-secret SEC [--redirect-port P] [--sheet-id ID]` | Ghi OAuth (và tuỳ chọn Sheet ID, port) vào `config.json`. |
+| `copyhub login` | Luồng OAuth + setup trình duyệt. |
+| `copyhub logout` | Xóa `tokens.json` (chưa xóa config). |
+| `copyhub status` | OAuth, Sheet, token, overlay, daemon. |
+| `copyhub start [--no-sheet] [--no-overlay] [--foreground]` | Mặc định **nền**; một instance. |
+| `copyhub list` / `copyhub ls` | PID daemon (nếu có). |
+| `copyhub stop` | Dừng daemon và overlay con. |
+| `copyhub overlay` | Chỉ cửa sổ Electron (không clipboard daemon). |
+| `copyhub reset --yes` | **Xóa toàn bộ** `~/.copyhub` (config, token, history, run state). Dữ liệu `.env` ngoài thư mục không đụng. |
+| `copyhub commands` / `copyhub cmds` | Liệt kê lệnh nhanh. |
+| `copyhub --help` | Trợ giúp Commander. |
 
-   - Or run **`copyhub config`**:
+---
 
-```bash
-copyhub config --client-id "<ID>" --client-secret "<SECRET>" [--sheet-id "<SPREADSHEET_ID>"] [--redirect-port 19999]
-```
+## Biến môi trường / Environment variables
 
-## First run
+| Biến | Ý nghĩa |
+|------|---------|
+| `COPYHUB_GOOGLE_CLIENT_ID` | OAuth Client ID (chỉ hiệu lực khi config **không** có đủ cặp ID+Secret). |
+| `COPYHUB_GOOGLE_CLIENT_SECRET` | OAuth Client Secret (cùng điều kiện trên). |
+| `COPYHUB_OAUTH_REDIRECT_PORT` | Port localhost cho OAuth (mặc định `19999`). Phải khớp redirect URI trong Google Console. |
+| `COPYHUB_OVERLAY_ACCELERATOR` | Phím tắt Electron ([Accelerator](https://www.electronjs.org/docs/latest/api/accelerator)); **ghi đè** giá trị trong config nếu set. |
+| `COPYHUB_START_NO_OVERLAY` | `=1` → `copyhub start` không spawn overlay. |
+| `COPYHUB_OVERLAY_STICKY` | `=1` → overlay không tự ẩn khi blur (chỉ Esc / chọn dòng). |
+| `COPYHUB_OVERLAY_HIDE_ON_START` | `=1` → không show cửa sổ lúc khởi động overlay (mở bằng shortcut/tray). |
+| `COPYHUB_OVERLAY_SKIP_TASKBAR` | `=1` → ẩn khỏi taskbar (Windows/Electron). |
+| `COPYHUB_POLL_MS` | Chu kỳ đọc clipboard (ms). |
 
-1. **Login** — opens the browser:
+Electron được spawn kế thừa `process.env` của daemon/CLI nên các biến trên áp dụng sau khi có trong môi trường tiến trình cha.
 
-   ```bash
-   copyhub login
-   ```
+---
 
-   - If Client ID / Secret are **not** already in `.env` or `~/.copyhub/config.json`, the first screen collects them (**Google OAuth credentials** page). Submit it to save into config.
-   - After Google sign-in, another setup page asks for **Spreadsheet ID**, **platform**, and optional **overlay shortcut**.
+## Thư mục dữ liệu / Data directory
 
-2. On that spreadsheet/setup page, enter your **Spreadsheet ID** (from the URL `…/d/<SPREADSHEET_ID>/edit`), choose **platform** (Windows / macOS / Linux) for shortcut hints, set the **overlay accelerator** if you want, and save.
+Mọi thứ dưới **`~/.copyhub/`** (Windows: **`%USERPROFILE%\.copyhub`**):
 
-3. **Start** the background watcher (clipboard + Sheets + overlay by default):
+| File | Nội dung |
+|------|-----------|
+| `config.json` | OAuth (`clientId`, `clientSecret`, `redirectPort`), `googleSheetId`, `overlayAccelerator`, `overlayPlatform`, … |
+| `tokens.json` | Refresh / access token OAuth |
+| `history.jsonl` | Lịch sử clipboard (JSON Lines) |
+| `run.json` | PID và metadata khi `copyhub start` chạy nền |
 
-   ```bash
-   copyhub start
-   ```
+---
+
+## Google Sheets
+
+- Append dòng khi bật Sheet và đã login token hợp lệ.  
+- Tab mới theo **ngày lịch máy**: `COPYHUB-YYYY-MM-DD`.  
+- Sheet phải được share cho đúng Google account đã OAuth (hoặc là spreadsheet của chính user đó).  
+- Nếu API báo disabled / permission: xem log — README có link Enable API trong một số thông báo lỗi được format sẵn trong code.
+
+---
+
+## Overlay (Electron)
+
+- Phím mặc định (**mọi hệ**, kể cả macOS): **`Control+Shift+H`** — phím **⌃ Control** (góc dưới trái trên bàn phím Apple) hoặc **Ctrl** (bàn phím PC), **cùng một vị trí quen thuộc**, không phụ thuộc ⌘ / Win.
+- Muốn dùng **⌘ Command + Shift + H** trên Mac: chỉnh `overlayAccelerator` trong `~/.copyhub/config.json`, đặt `COPYHUB_OVERLAY_ACCELERATOR`, hoặc chọn preset trên trang setup (`CommandOrControl+Shift+H` / `Command+Shift+H`).
+- **macOS**: vẫn có thể cần quyền **Accessibility** (*Privacy & Security*) cho **Terminal** / tiến trình chạy Electron nếu phím global không hoạt động.
+- Overlay có phân trang ~10 mục; Sheet load dần khi cần (không gom hết tab một lần).  
+- Click ra ngoài cửa sổ thường đóng overlay (trừ khi `COPYHUB_OVERLAY_STICKY=1`). **Esc** đóng.
 
-   You can close the terminal; the process keeps running. Check with `copyhub list` and stop with `copyhub stop`.
+---
 
-### Useful flags and environment variables
+## Clipboard & lịch sử
 
-| Action | How |
-|--------|-----|
-| Run in terminal (Ctrl+C stops everything) | `copyhub start --foreground` |
-| No Google Sheets | `copyhub start --no-sheet` |
-| No Electron overlay | `copyhub start --no-overlay` or `COPYHUB_START_NO_OVERLAY=1` |
-| Override shortcut | `COPYHUB_OVERLAY_ACCELERATOR` in `.env` (overrides saved config) |
-| Overlay stays open when clicking outside | `COPYHUB_OVERLAY_STICKY=1` |
+- Watcher bỏ qua clipboard trùng hash liên tiếp.  
+- Trước khi ghi file/Sheet, nếu nội dung **trùng hệt bản mới nhất** trong `history.jsonl` thì **bỏ qua** (tránh copy lại cùng chuỗi sau khi đổi clipboard khác rồi copy lại).
 
-Run `copyhub --help` or `copyhub commands` for built-in help.
+---
 
-## CLI commands
+## Nâng cấp / Updating
 
-Quick reference (same as `copyhub commands`):
+Dữ liệu `~/.copyhub` được giữ khi nâng cấp package.
 
 ```bash
-copyhub config --client-id "<ID>" --client-secret "<SECRET>" [--redirect-port 19999] [--sheet-id "<SPREADSHEET_ID>"]
-copyhub login
-copyhub logout
-copyhub status
-copyhub start [--no-sheet] [--no-overlay] [--foreground]
-copyhub list    # alias: copyhub ls
 copyhub stop
-copyhub overlay
-copyhub commands    # alias: copyhub cmds
-copyhub --help
+npm install -g copyhub-cli@latest
+copyhub start
 ```
 
-| Command | What it does |
-|---------|----------------|
-| `copyhub config` | Writes OAuth client ID/secret (and optional Sheet ID, redirect port) to `~/.copyhub/config.json`. `--client-id` and `--client-secret` are required. |
-| `copyhub login` | Opens browser: localhost wizard for Client ID/secret if missing, then Google OAuth, then spreadsheet/platform setup. |
-| `copyhub logout` | Deletes saved OAuth tokens (`~/.copyhub/tokens.json`). |
-| `copyhub status` | Prints OAuth config source, sheet target, tokens, overlay settings, and whether the background daemon is running. |
-| `copyhub start` | Starts clipboard watcher + optional Sheets sync + Electron overlay in the **background** (closing the terminal does not stop it). Only one instance at a time. |
-| `copyhub start --foreground` | Same as above but attached to the terminal; **Ctrl+C** stops everything. |
-| `copyhub start --no-sheet` | Local history only; no Google Sheets writes. |
-| `copyhub start --no-overlay` | No Electron window; use env `COPYHUB_START_NO_OVERLAY=1` for the same effect. |
-| `copyhub list` / `copyhub ls` | Shows PID and start time if the daemon from `copyhub start` is running. |
-| `copyhub stop` | Stops the background daemon and its overlay child process. |
-| `copyhub overlay` | Runs **only** the Electron overlay (no clipboard daemon). Useful if you run the daemon separately or for debugging. |
+Từ source: `git pull`, `npm install`, rồi `copyhub start` (hoặc `npm link` nếu dev).
 
-## Data locations
+---
 
-Everything lives under **`~/.copyhub/`** (or `%USERPROFILE%\.copyhub` on Windows):
+## Xử lý sự cố / Troubleshooting
 
-| File | Contents |
-|------|----------|
-| `config.json` | OAuth credentials (if not only in `.env`), `googleSheetId`, `overlayAccelerator`, `overlayPlatform` |
-| `tokens.json` | OAuth refresh/access tokens |
-| `history.jsonl` | Local clipboard history (JSON Lines) |
-| `run.json` | Daemon PID and metadata (when using `copyhub start` without `--foreground`) |
+### `invalid_client` hoặc “client secret is invalid” sau khi đăng nhập Google
 
-## Google Sheets layout
+- Dùng OAuth client **Web application**, redirect đúng `http://127.0.0.1:<port>/oauth2callback`.  
+- Reset secret hoặc **Download JSON** client mới; nhập lại qua wizard; trên Mac **xóa ô** trước khi dán.  
+- `copyhub status` — xem nguồn Client ID/Secret.  
+- Chi tiết thêm: CopyHub có trang lỗi HTML khi đổi `code` token thất bại.
 
-- Rows are appended when Sheet sync is enabled and you are logged in.
-- New tabs are created per **local calendar day**, named: **`COPYHUB-YYYY-MM-DD`**.
+### Port OAuth đã được dùng (`EADDRINUSE`)
 
-## Overlay (Electron)
+Đổi port: `COPYHUB_OAUTH_REDIRECT_PORT` hoặc `copyhub config … --redirect-port P`, và cập nhật redirect URI trong Google Console.
+
+### `copyhub start` báo đã chạy
+
+Một instance nền: `copyhub list` / `copyhub stop` rồi start lại.
+
+### Sheet không ghi / lỗi API
+
+- Bật Google Sheets API đúng project.  
+- Kiểm tra `copyhub status` (token, Sheet ID).  
+- Share spreadsheet cho account đã login.
+
+### Overlay không mở / phím không hoạt động
+
+- **macOS**: bật **Accessibility** cho Terminal / Node / Electron.  
+- Mặc định là **Control+Shift+H** (⌃ hoặc Ctrl + Shift + H), không dùng phím Win.  
+- Đảm bảo daemon đang chạy (`copyhub list`) hoặc thử `copyhub overlay`.  
+- Tránh trùng phím với app khác (Spotlight, Alfred, …).
+
+### Xóa sạch cấu hình và làm lại
+
+```bash
+copyhub stop
+copyhub reset --yes
+```
+
+Sau đó xóa hoặc sửa `COPYHUB_GOOGLE_*` trong shell/`~/.copyhub/.env` nếu không muốn dùng env nữa. `.env` **không** bị `reset` xóa.
 
-- Global shortcut defaults to **`CommandOrControl+Shift+H`** if nothing else is set (`Ctrl+Shift+H` on Windows/Linux, `⌘⇧H` on macOS-style wording in Electron).
-- **macOS**: you may need to grant **Accessibility** permissions for global shortcuts.
-- Some **`Control+Alt+…`** combinations do not register reliably on Windows; prefer alternatives suggested on the setup page.
+---
 
-## Troubleshooting: `invalid_client` after Google sign-in
+## Bảo mật / Security notes
 
-That response comes from Google’s token endpoint when the **Client ID + Client Secret pair** does not match your OAuth client.
+- `config.json` và `tokens.json` chứa bí mật OAuth — quyền file thư mục user (`~/.copyhub`).  
+- Không commit `.env` hoặc copyhub data vào git công khai.
 
-1. **Use a “Web application” OAuth client** (not iOS/Android/Desktop-only flows meant for different redirect rules). Add **Authorized redirect URI**: `http://127.0.0.1:19999/oauth2callback` (change the port if you use `COPYHUB_OAUTH_REDIRECT_PORT` or saved `redirectPort`).
-2. **Where credentials come from**: If **`~/.copyhub/config.json` contains both Client ID and Secret** (wizard or `copyhub config`), CopyHub uses **that pair** for OAuth — env vars are **ignored** for those two fields until you remove them from config. If config does **not** have both, CopyHub uses **`COPYHUB_GOOGLE_CLIENT_ID` / `COPYHUB_GOOGLE_CLIENT_SECRET`** from the environment / `.env`. CopyHub never mixes env Client ID with file Secret (that mismatch triggers `invalid_client`).
-3. **Paste cleanly**: Re-open the localhost credential wizard or edit `config.json` so ID and secret have **no extra spaces or line breaks**.
-4. Run **`copyhub status`** and confirm **Client ID/Secret source** matches what you expect.
+---
 
-## License
+## Giấy phép / License
 
-MIT — see `package.json`.
+MIT — xem `package.json`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "copyhub-cli",
-  "version": "1.0.5",
+  "version": "1.0.8",
   "description": "CopyHub — clipboard, local history, Google Sheets sync (OAuth). Windows, macOS, Linux.",
   "type": "module",
   "bin": {

package/src/config.js

@@ -22,6 +22,34 @@ function parseRedirectPortFromEnv() {
   return n;
 }
 
+/**
+ * Strip invisible / stray characters from pasted OAuth credentials (fixes many Mac copy-paste issues).
+ * @param {unknown} raw
+ * @returns {string}
+ */
+export function sanitizeOAuthCredentialInput(raw) {
+  if (raw == null) return '';
+  let s = String(raw);
+  s = s.replace(/^\uFEFF/, '');
+  s = s.replace(/[\u200b-\u200d\u2060]/g, '');
+  s = s.replace(/\r/g, '');
+  s = s.replace(/[\u00a0\u202f\u2007]/g, ' ');
+  s = s.trim();
+  if (
+    (s.startsWith('"') && s.endsWith('"')) ||
+    (s.startsWith("'") && s.endsWith("'"))
+  ) {
+    s = s.slice(1, -1).trim();
+  }
+  if (
+    (s.startsWith('\u201c') && s.endsWith('\u201d')) ||
+    (s.startsWith('\u2018') && s.endsWith('\u2019'))
+  ) {
+    s = s.slice(1, -1).trim();
+  }
+  return s;
+}
+
 /**
  * Port for the OAuth HTTP listener (env wins, then saved config, then default).
  * Does not require Client ID / Secret (used before credential bootstrap).
@@ -44,8 +72,8 @@ export function resolveOAuthListenPort() {
 
 /** Both Client ID and Secret come from environment (or .env). */
 export function hasOAuthCredentialsInEnv() {
-  const id = process.env[ENV_GOOGLE_CLIENT_ID]?.trim();
-  const sec = process.env[ENV_GOOGLE_CLIENT_SECRET]?.trim();
+  const id = sanitizeOAuthCredentialInput(process.env[ENV_GOOGLE_CLIENT_ID]);
+  const sec = sanitizeOAuthCredentialInput(process.env[ENV_GOOGLE_CLIENT_SECRET]);
   return Boolean(id && sec);
 }
 
@@ -58,8 +86,10 @@ export function describeEffectiveOAuthCredentialSource() {
   if (existsSync(CONFIG_PATH)) {
     try {
       const j = JSON.parse(readFileSync(CONFIG_PATH, 'utf8'));
-      const id = typeof j.clientId === 'string' ? j.clientId.trim() : '';
-      const sec = typeof j.clientSecret === 'string' ? j.clientSecret.trim() : '';
+      const id =
+        typeof j.clientId === 'string' ? sanitizeOAuthCredentialInput(j.clientId) : '';
+      const sec =
+        typeof j.clientSecret === 'string' ? sanitizeOAuthCredentialInput(j.clientSecret) : '';
       filePair = Boolean(id && sec);
     } catch {
       /* ignore */
@@ -88,11 +118,11 @@ export async function loadConfig() {
     const raw = await readFile(CONFIG_PATH, 'utf8');
     const j = JSON.parse(raw);
     if (typeof j.clientId === 'string') {
-      const id = j.clientId.trim();
+      const id = sanitizeOAuthCredentialInput(j.clientId);
       if (id) fromFile.clientId = id;
     }
     if (typeof j.clientSecret === 'string') {
-      const sec = j.clientSecret.trim();
+      const sec = sanitizeOAuthCredentialInput(j.clientSecret);
       if (sec) fromFile.clientSecret = sec;
     }
     if (typeof j.redirectPort === 'number' && Number.isFinite(j.redirectPort)) {
@@ -100,8 +130,8 @@ export async function loadConfig() {
     }
   }
 
-  const envId = process.env[ENV_GOOGLE_CLIENT_ID]?.trim() ?? '';
-  const envSecret = process.env[ENV_GOOGLE_CLIENT_SECRET]?.trim() ?? '';
+  const envId = sanitizeOAuthCredentialInput(process.env[ENV_GOOGLE_CLIENT_ID]);
+  const envSecret = sanitizeOAuthCredentialInput(process.env[ENV_GOOGLE_CLIENT_SECRET]);
   const envPort = parseRedirectPortFromEnv();
 
   const filePort =
@@ -208,10 +238,14 @@ export async function mergeConfigPartial(partial) {
   const out = { ...existing, ...partial };
   delete out.sheetTab;
   delete out.sheetDailyPrefix;
-  for (const key of ['clientId', 'clientSecret', 'googleSheetId']) {
-    if (typeof out[key] === 'string') {
-      out[key] = /** @type {string} */ (out[key]).trim();
-    }
+  if (typeof out.clientId === 'string') {
+    out.clientId = sanitizeOAuthCredentialInput(out.clientId);
+  }
+  if (typeof out.clientSecret === 'string') {
+    out.clientSecret = sanitizeOAuthCredentialInput(out.clientSecret);
+  }
+  if (typeof out.googleSheetId === 'string') {
+    out.googleSheetId = sanitizeOAuthCredentialInput(out.googleSheetId);
   }
   await writeFile(CONFIG_PATH, JSON.stringify(out, null, 2), 'utf8');
 }
@@ -232,11 +266,16 @@ export async function saveConfig(cfg) {
   }
   const out = {
     ...existing,
-    clientId: cfg.clientId.trim(),
-    clientSecret: cfg.clientSecret.trim(),
+    clientId: sanitizeOAuthCredentialInput(cfg.clientId),
+    clientSecret: sanitizeOAuthCredentialInput(cfg.clientSecret),
     redirectPort: cfg.redirectPort ?? DEFAULT_OAUTH_REDIRECT_PORT,
   };
-  if (cfg.googleSheetId !== undefined) out.googleSheetId = cfg.googleSheetId;
+  if (cfg.googleSheetId !== undefined) {
+    out.googleSheetId =
+      typeof cfg.googleSheetId === 'string'
+        ? sanitizeOAuthCredentialInput(cfg.googleSheetId)
+        : cfg.googleSheetId;
+  }
   delete out.sheetTab;
   delete out.sheetDailyPrefix;
   await writeFile(CONFIG_PATH, JSON.stringify(out, null, 2), 'utf8');

package/src/oauth.js

@@ -14,6 +14,7 @@ import {
   loadSheetSyncTarget,
   loadOverlayAcceleratorFromConfigSync,
   loadOverlayPlatformFromConfigSync,
+  sanitizeOAuthCredentialInput,
 } from './config.js';
 import { saveTokens, loadTokens } from './tokens.js';
 import { TOKENS_PATH } from './paths.js';
@@ -90,10 +91,15 @@ function formatOAuthTokenExchangeMessage(err) {
   const fallback = /** @type {Error} */ (err)?.message || String(err);
 
   if (code === 'invalid_client') {
+    const secretInvalid = /client secret is invalid|invalid_client_secret/i.test(desc);
+    const secretHint = secretInvalid
+      ? 'Google says the Client Secret is wrong for this Client ID. Open Cloud Console → APIs & Services → Credentials → your Web client → reset secret or download JSON again; paste client_id and client_secret from that JSON into the CopyHub wizard (Safari/Chrome may autofill an old secret — clear fields first). '
+      : '';
     return (
       'OAuth invalid_client: Google rejected the Client ID / Client Secret pair. ' +
-      'In Google Cloud Console use OAuth client type "Web application" and add redirect URI http://127.0.0.1:<port>/oauth2callback (port matches CopyHub). Paste fresh credentials into the wizard — no spaces before/after. ' +
-      'If COPYHUB_GOOGLE_CLIENT_ID / COPYHUB_GOOGLE_CLIENT_SECRET are set in your shell or ~/.copyhub/.env, set BOTH to match that client or unset both so credentials from ~/.copyhub/config.json are used (CopyHub never mixes env ID with file secret). ' +
+      secretHint +
+      'Use OAuth client type "Web application" and add redirect URI http://127.0.0.1:<port>/oauth2callback (port matches CopyHub). Prefer pasting values from the client\'s Download JSON file to avoid typos. ' +
+      'If COPYHUB_GOOGLE_CLIENT_ID / COPYHUB_GOOGLE_CLIENT_SECRET exist in shell or ~/.copyhub/.env, they must match this client or remove both so ~/.copyhub/config.json is used. ' +
       (desc ? `Google says: ${desc}` : `(${fallback})`)
     );
   }
@@ -228,6 +234,7 @@ function credentialSetupPageHtml(bootstrapToken, listenPort) {
     <div class="brand">CopyHub</div>
     <h1>Google Cloud OAuth</h1>
     <p class="sub">Paste your OAuth 2.0 Client ID and Client Secret (same as <code>${ENV_GOOGLE_CLIENT_ID}</code> / <code>${ENV_GOOGLE_CLIENT_SECRET}</code> in <code>.env</code>). Stored in <code>~/.copyhub/config.json</code>. After saving here, CopyHub uses this pair for sign-in — not leftover variables from shell or <code>.env</code>.</p>
+    <p class="hint" style="margin-bottom:20px;"><strong>Mac / Safari:</strong> copy from Google Cloud → Credentials → your <strong>Web client</strong> → <strong>Download JSON</strong> and paste <code>client_id</code> / <code>client_secret</code> exactly. Clear both fields if the browser autofills an old secret.</p>
 
     <div class="card">
       <p class="hint" style="margin-top:0;"><strong>Authorized redirect URI</strong> in Google Cloud Console must include:</p>
@@ -235,13 +242,13 @@ function credentialSetupPageHtml(bootstrapToken, listenPort) {
       <p class="hint">Port comes from <code>${ENV_OAUTH_REDIRECT_PORT}</code> (currently <strong>${listenPort}</strong>) or your saved config.</p>
     </div>
 
-    <form method="POST" action="/credentials">
+    <form method="POST" action="/credentials" autocomplete="off">
       <input type="hidden" name="t" value="${tVal}" />
       <div class="card">
         <label class="field-label" for="cid">Client ID</label>
-        <input id="cid" type="text" name="clientId" autocomplete="off" spellcheck="false" required />
+        <input id="cid" type="text" name="clientId" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false" required />
         <label class="field-label" for="csec" style="margin-top:16px;">Client secret</label>
-        <input id="csec" type="password" name="clientSecret" autocomplete="new-password" spellcheck="false" required />
+        <input id="csec" type="text" name="clientSecret" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false" required placeholder="Usually starts with GOCSPX-" />
       </div>
       <button type="submit" class="submit">Save and continue to Google sign-in</button>
     </form>
@@ -316,8 +323,8 @@ async function runCredentialBootstrap() {
             res.end('Forbidden');
             return;
           }
-          const clientId = (params.get('clientId') || '').trim();
-          const clientSecret = (params.get('clientSecret') || '').trim();
+          const clientId = sanitizeOAuthCredentialInput(params.get('clientId'));
+          const clientSecret = sanitizeOAuthCredentialInput(params.get('clientSecret'));
           if (!clientId || !clientSecret) {
             res.writeHead(400, { 'Content-Type': 'text/html; charset=utf-8' });
             res.end('<p>Client ID and Client secret are required.</p>');
@@ -376,18 +383,20 @@ async function runCredentialBootstrap() {
 /** Shortcut presets (Electron Accelerator) per platform — embedded as JSON in the setup page. */
 const PLATFORM_PRESETS = {
   win: [
-    { label: 'Ctrl + Shift + H · recommended', value: 'CommandOrControl+Shift+H' },
-    { label: 'Control + Shift + H', value: 'Control+Shift+H' },
+    { label: 'Ctrl + Shift + H · recommended', value: 'Control+Shift+H' },
     { label: 'Alt + Shift + H', value: 'Alt+Shift+H' },
   ],
   mac: [
-    { label: '⌘ + Shift + H · recommended', value: 'CommandOrControl+Shift+H' },
-    { label: 'Command + Shift + H', value: 'Command+Shift+H' },
+    {
+      label: '⌃ Control + Shift + H · recommended (Apple & PC keyboards)',
+      value: 'Control+Shift+H',
+    },
+    { label: '⌘ Command + Shift + H', value: 'CommandOrControl+Shift+H' },
+    { label: 'Command + Shift + H (explicit ⌘)', value: 'Command+Shift+H' },
     { label: '⌘ + Shift + V', value: 'Command+Shift+V' },
   ],
   linux: [
-    { label: 'Ctrl + Shift + H · recommended', value: 'CommandOrControl+Shift+H' },
-    { label: 'Control + Shift + H', value: 'Control+Shift+H' },
+    { label: 'Ctrl + Shift + H · recommended', value: 'Control+Shift+H' },
     { label: 'Alt + Shift + H', value: 'Alt+Shift+H' },
   ],
 };
@@ -625,7 +634,7 @@ function setupPageHtml(setupToken, currentSheetId, currentAccelerator, currentPl
           <button type="button" class="platform-btn" data-platform="mac" aria-pressed="false">
             <span class="ico" aria-hidden="true">⌘</span>
             <span class="name">macOS</span>
-            <span class="tag">⌘ Command</span>
+            <span class="tag">⌃ Control default</span>
           </button>
           <button type="button" class="platform-btn" data-platform="linux" aria-pressed="false">
             <span class="ico" aria-hidden="true">🐧</span>
@@ -634,10 +643,10 @@ function setupPageHtml(setupToken, currentSheetId, currentAccelerator, currentPl
           </button>
         </div>
 
-        <label class="field-label" for="acc">Accelerator (blank = default Ctrl/⌘ + Shift + H)</label>
+        <label class="field-label" for="acc">Accelerator (blank = Control + Shift + H)</label>
         <input id="acc" type="text" name="overlayAccelerator" value="${accVal}" placeholder="Pick a preset below or type your own" autocomplete="off" spellcheck="false" />
 
-        <p class="hint">On Windows use <code>Control</code> in config, not <code>Ctrl</code>. Avoid <code>Control+Alt+…</code> (often grabbed by drivers).</p>
+        <p class="hint">Default everywhere: <code>Control+Shift+H</code> (⌃ or Ctrl + Shift + H — same key on Mac Apple keyboard & PC keyboard). On Windows type <code>Control</code> in config, not <code>Ctrl</code>. Avoid <code>Control+Alt+…</code> (often grabbed by drivers).</p>
         <p class="hint"><code>COPYHUB_OVERLAY_ACCELERATOR</code> in <code>.env</code>, if set, overrides this value.</p>
 
         <div id="chipRegion" class="chips" aria-live="polite"></div>
@@ -663,9 +672,9 @@ function setupPageHtml(setupToken, currentSheetId, currentAccelerator, currentPl
       var btns = document.querySelectorAll('.platform-btn');
 
       var hints = {
-        win: 'Windows: CommandOrControl = Ctrl.',
-        mac: 'macOS: CommandOrControl = ⌘ Command.',
-        linux: 'Linux: same as Windows with Ctrl; clipboard depends on your desktop.'
+        win: 'Windows: default Control+Shift+H.',
+        mac: 'macOS: default ⌃ Control+Shift+H (same as Ctrl on a PC keyboard). Use a ⌘ preset only if you prefer Command.',
+        linux: 'Linux: default Control+Shift+H; clipboard depends on your desktop.'
       };
 
       function setPlatform(p) {

package/ui/main.mjs

@@ -32,7 +32,7 @@ const __dirname = path.dirname(fileURLToPath(import.meta.url));
 /** Set to 1 so the window does not hide on blur (only Esc / pick row to copy). */
 const STICKY_NO_BLUR = process.env.COPYHUB_OVERLAY_STICKY === '1';
 
-/** Electron Accelerator: use `Control`, not `Ctrl`; `CommandOrControl` = Ctrl (Win) / Cmd (Mac). */
+/** Electron Accelerator: use `Control`, not `Ctrl`; avoid bare `Ctrl` in strings — Electron expects `Control`. */
 function normalizeAccelerator(raw) {
   if (!raw || typeof raw !== 'string') return '';
   let s = raw.trim();
@@ -42,7 +42,8 @@ function normalizeAccelerator(raw) {
   return s;
 }
 
-const DEFAULT_ACCEL = 'CommandOrControl+Shift+H';
+/** Same physical ⌃ / Ctrl key on Mac (Apple & Windows-layout keyboards) and on Win/Linux — one default everywhere. */
+const DEFAULT_ACCEL = 'Control+Shift+H';
 const HIDE_ON_START = process.env.COPYHUB_OVERLAY_HIDE_ON_START === '1';
 
 /** Overlay size (slightly larger than earlier ~70% width). */
@@ -213,7 +214,7 @@ function toggleOverlay() {
 }
 
 /**
- * Register global shortcut: try .env (normalized) then default CommandOrControl+Shift+H.
+ * Register global shortcut: try .env / saved config (normalized) then default Control+Shift+H.
  * @returns {{ accelerator: string, usedFallback: boolean }}
  */
 function registerHotkeys() {
@@ -546,12 +547,12 @@ if (gotLock) {
     };
     if (accelerator) {
       console.log('CopyHub overlay — shortcut in use:', accelerator);
-      console.log('Windows tip: Ctrl+Shift+H (CommandOrControl+Shift+H).');
+      console.log('Default shortcut: Control+Shift+H (⌃ or Ctrl + Shift + H).');
       if (usedFallback) {
         console.warn(
-          'COPYHUB_OVERLAY_ACCELERATOR could not be registered. Using default CommandOrControl+Shift+H.',
+          'COPYHUB_OVERLAY_ACCELERATOR could not be registered. Using default Control+Shift+H.',
         );
-        console.warn('Leave COPYHUB_OVERLAY_ACCELERATOR unset in .env to always use Ctrl+Shift+H.');
+        console.warn('Leave COPYHUB_OVERLAY_ACCELERATOR unset to use the default Control+Shift+H.');
       }
     } else {
       console.error(