Add copy-only, color swatches, DB speed pragmas, and living docs
- Copy only (right-click -> Copy): write to clipboard without auto-pasting or hiding the window - Color swatches: hex/rgb/hsl entries show a preview chip - SQLite WAL + synchronous=NORMAL so the UI can read while the clipboard poller writes - Memoize list rows (React.memo) so selection/focus changes don't re-render every row's preview - Add docs/GUIDE.md (living install + usage doc), docs/SHARING.md, docs/TESTING.md, docs/LAUNCH-AT-LOGIN.md, docs/PRODUCT.md, CHANGELOG.md, ROADMAP.md - Add homelab Gitea Actions CI (.gitea/workflows/ci.yml) + gitleaks allowlist - Bump version to 0.2.0
This commit is contained in:
+155
@@ -0,0 +1,155 @@
|
||||
# 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 |
|
||||
| Pin (keep forever, always on top) | Right-click → **Pin** / **Unpin** |
|
||||
| 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).
|
||||
Reference in New Issue
Block a user