ilia
f9a11ca640
Control+click was treated as multi-select and a window click listener dismissed the menu before Pin/Delete could run; fire menu actions on mousedown and close only on outside pointerdown.
158 lines
6.5 KiB
Markdown
158 lines
6.5 KiB
Markdown
# maCopy — Install & Usage Guide
|
||
|
||
The single living reference for **installing** and **using** maCopy.
|
||
Update this whenever a shortcut, setting, or behavior changes — this is
|
||
the doc a new user (including future-you) should be able to follow start
|
||
to finish without reading any source code.
|
||
|
||
Current version: see [CHANGELOG.md](../CHANGELOG.md). Feature backlog:
|
||
[ROADMAP.md](../ROADMAP.md).
|
||
|
||
---
|
||
|
||
## 1. Install
|
||
|
||
### Option A — you already have a built DMG/app
|
||
|
||
1. Double-click the DMG, drag **maCopy.app** into **Applications**.
|
||
2. First launch: Gatekeeper will likely warn the app is unverified
|
||
(it's ad-hoc signed, not notarized yet — see
|
||
[docs/SHARING.md](SHARING.md)). Right-click the app → **Open** → confirm.
|
||
3. macOS will prompt for **Accessibility** permission the first time you
|
||
try to paste — this is required for auto-paste (`Cmd+V` simulation).
|
||
System Settings → Privacy & Security → Accessibility → enable maCopy.
|
||
4. Look for the maCopy icon in the menu bar (top-right). No Dock icon —
|
||
that's expected, it's a menu-bar-only app.
|
||
|
||
### Option B — build it yourself
|
||
|
||
Requirements: macOS 10.15+, [Rust](https://rustup.rs) 1.77+, Node 18+,
|
||
Xcode Command Line Tools (`xcode-select --install`).
|
||
|
||
```bash
|
||
git clone gitea@git.levkin.ca:ilia/maCopy.git
|
||
cd maCopy
|
||
npm install
|
||
npm run tauri build
|
||
open src-tauri/target/release/bundle/macos/maCopy.app
|
||
```
|
||
|
||
Copy the resulting `.app` to `/Applications` if you want **Launch at
|
||
login** to stick across rebuilds (see step 4 below).
|
||
|
||
### First-run checklist
|
||
|
||
- [ ] App icon visible in the menu bar
|
||
- [ ] Accessibility permission granted (Settings → Privacy & Security → Accessibility)
|
||
- [ ] Global hotkey `` Ctrl+` `` opens/closes the picker
|
||
- [ ] (Optional) Settings → **Launch at login** turned on
|
||
|
||
---
|
||
|
||
## 2. Everyday usage
|
||
|
||
### Opening the picker
|
||
|
||
| Action | How |
|
||
|---|---|
|
||
| Open/close | Click the menu bar icon, or press `` Ctrl+` `` |
|
||
| Dismiss | `Escape`, or click outside the window |
|
||
|
||
The hotkey is configurable — Settings → **Global hotkey** → click the
|
||
field → press your new combo.
|
||
|
||
### Pasting
|
||
|
||
| Action | How |
|
||
|---|---|
|
||
| Paste an item into the app you were just using | Click it, or select + `Enter` |
|
||
| Paste **plain** (strip formatting) | `⌥`/`Alt` + click, or right-click → **Paste plain** |
|
||
| Paste with a transform | Right-click → **Transform** → pick one |
|
||
| Paste the Nth item directly (no picker needed) | `Cmd+1` … `Cmd+9` while picker is open |
|
||
| Copy to clipboard **without** auto-pasting | Right-click → **Copy** |
|
||
|
||
**Transforms** (right-click → Transform): trim whitespace, UPPERCASE /
|
||
lowercase / Title Case, collapse whitespace/newlines, pretty-print JSON,
|
||
join to a single line. Transforms apply just before the paste — the
|
||
saved history entry is never modified.
|
||
|
||
### Selecting & managing history
|
||
|
||
| Action | How |
|
||
|---|---|
|
||
| Multi-select | `Cmd+Click` to toggle one, `Shift+Click`/`Shift+Arrow` for a range, `Cmd+A` for all |
|
||
| Paste multiple selected items (joined with newlines) | `Enter` |
|
||
| Delete | `Backspace`/`Delete` with items selected, or right-click → **Delete** |
|
||
| Pin (keep forever, always on top) | Right-click → **Pin** / **Unpin** |
|
||
|
||
On macOS, **Control+click** opens the context menu (same as right-click). Use **Cmd+Click** for multi-select — Control+click is not multi-select.
|
||
| Search | Just start typing — instant full-text search |
|
||
|
||
### What you'll see in the list
|
||
|
||
- **Images** show a small thumbnail; the full-resolution image stays in
|
||
the database and is only loaded when you actually paste.
|
||
- **Colors** — an entry that's *exactly* a hex/rgb/hsl value (e.g.
|
||
`#3366ff`) shows a small color chip next to it.
|
||
- **Sensitive items** (passwords, card numbers, banking details) show
|
||
`••` and a redacted preview in the list — the real value is still
|
||
stored and still pastes correctly. See "Privacy" below.
|
||
- **PIN** badge — pinned items, always sorted to the top, never
|
||
auto-trimmed.
|
||
- `⌘1`–`⌘9` badges on the first nine rows — quick-paste reference.
|
||
|
||
### Settings panel
|
||
|
||
Menu bar icon → **Settings…**
|
||
|
||
| Setting | What it does |
|
||
|---|---|
|
||
| Global hotkey | Re-bind the open/close shortcut |
|
||
| Show images | Toggle thumbnail rendering in the list (off = faster on huge histories) |
|
||
| Max history | 1K / 5K / 10K / 50K entries kept before auto-trim (pinned items are exempt) |
|
||
| Window position | Near cursor, center, or a screen corner |
|
||
| Launch at login | Registers/unregisters a macOS Login Item — see [docs/LAUNCH-AT-LOGIN.md](LAUNCH-AT-LOGIN.md) |
|
||
| Pause monitoring | Tray menu checkbox — temporarily stop capturing new clipboard content |
|
||
|
||
---
|
||
|
||
## 3. Privacy — what gets captured and how
|
||
|
||
- Whitespace-only clipboard content is ignored (never saved).
|
||
- Password/card/banking-looking text is detected and **redacted in the
|
||
list preview only** — the real value is still in the database (needed
|
||
so paste still works) and still pastes correctly.
|
||
- No network calls, no telemetry, no accounts. Everything lives in:
|
||
```
|
||
~/Library/Application Support/maCopy/clipboard.db
|
||
```
|
||
- You can pause monitoring any time from the tray menu.
|
||
- Full picture, including what's *not yet* implemented (encryption at
|
||
rest, per-app exclusions): [ROADMAP.md](../ROADMAP.md) → "Privacy & trust".
|
||
|
||
---
|
||
|
||
## 4. Troubleshooting
|
||
|
||
| Symptom | Fix |
|
||
|---|---|
|
||
| Hotkey does nothing | Settings → check it isn't a duplicate of a macOS shortcut (the old default `Cmd+\`` conflicted with window-cycling — current default is `` Ctrl+` ``) |
|
||
| Paste doesn't happen (item copies but old app doesn't receive it) | Grant **Accessibility** permission — System Settings → Privacy & Security → Accessibility → add/enable maCopy |
|
||
| App won't open ("cannot verify developer") | Right-click → Open, or `xattr -cr /Applications/maCopy.app` — see [docs/SHARING.md](SHARING.md) |
|
||
| Launch at login doesn't stick after rebuild | You're running a dev/rebuilt binary at a new path — install the `.app` under `/Applications` and re-toggle the setting |
|
||
| App feels slow / using lots of memory | Update to the latest build — see the performance notes in [README.md](../README.md#architecture); file it as a regression if it persists |
|
||
|
||
---
|
||
|
||
## 5. Where things live (quick reference)
|
||
|
||
| What | Path |
|
||
|---|---|
|
||
| App (after build) | `src-tauri/target/release/bundle/macos/maCopy.app` |
|
||
| Installer DMG | `src-tauri/target/release/bundle/dmg/maCopy_<version>_aarch64.dmg` |
|
||
| Your clipboard database | `~/Library/Application Support/maCopy/clipboard.db` |
|
||
| Source | this repo |
|
||
|
||
Sharing the app with someone else: [docs/SHARING.md](SHARING.md).
|
||
Full doc index: [docs/README.md](README.md).
|