2026-08-05 14:18:09 -05:00
1 changed files with 29 additions and 28 deletions
@@ -1,6 +1,6 @@
 # maCopy
-A fast, native macOS clipboard manager that lives in your menu bar. Built with Tauri 2, React, TypeScript, and SQLite.
+macOS clipboard manager in the menu bar. Built with Tauri 2, React, TypeScript, and SQLite.
 ![macOS](https://img.shields.io/badge/macOS-10.15+-black?logo=apple)
 ![Tauri](https://img.shields.io/badge/Tauri-2-blue?logo=tauri)
@@ -8,32 +8,33 @@ A fast, native macOS clipboard manager that lives in your menu bar. Built with T
 ## Features
- **Menu bar app** — no dock icon, stays out of your way
+| Area | Behavior |
- **Global hotkey** — `` Ctrl+` `` opens the window (doesn’t steal macOS Cmd+` window-cycle); configurable in Settings
+|------|----------|
- **Clipboard monitoring** — watches the macOS pasteboard changeCount (no busy hashing while idle); captures text, images, and file paths
+| Menu bar | No dock icon; lives in the tray |
- **Fast picker** — list API returns truncated previews only (image blobs stay in SQLite until paste); refreshes on copy / window focus instead of reloading everything every second
+| Global hotkey | `` Ctrl+` `` opens the window (does not steal macOS Cmd+` window-cycle); configurable in Settings |
- **Full-text search** — instant filtering via SQLite FTS5
+| Clipboard monitoring | Watches pasteboard changeCount; captures text, images, and file paths |
- **Quick paste** — `Cmd+1` through `Cmd+9` to paste the Nth item directly into the previous app
+| List performance | Truncated previews in list API; image blobs stay in SQLite until paste |
- **Paste & return** — clicking an entry copies it to clipboard, hides the window, and auto-pastes into the previously-focused app
+| Search | Full-text filtering via SQLite FTS5 |
- **Multi-select** — `Cmd+Click` to toggle, `Shift+Arrow` or `Shift+Click` to range-select, `Cmd+A` for all, `Enter` to paste selected
+| Quick paste | `Cmd+1` through `Cmd+9` paste the Nth item into the previous app |
- **Pin entries** — pinned items stay at the top and are never auto-deleted
+| Paste and return | Click copies, hides window, auto-pastes into the previously focused app |
- **Context menu** — right-click for Paste, Pin/Unpin, Delete (with multi-select support)
+| Multi-select | `Cmd+Click` toggle; `Shift+Arrow` or `Shift+Click` range; `Cmd+A` all; `Enter` to paste |
- **Resizable window** — drag edges to resize; size is remembered between sessions
+| Pin | Pinned items stay at top and skip auto-delete |
- **Window positioning** — choose where the window appears: near cursor, center, or any corner (configurable in Settings)
+| Context menu | Right-click: Paste, Pin/Unpin, Delete (multi-select aware) |
- **Auto-trim** — keeps up to 50K entries (configurable: 1K/5K/10K/50K); oversized images are skipped
+| Window | Resizable; size remembered; position: near cursor, center, or corner |
- **Dark/light mode** — follows macOS system appearance
+| Auto-trim | Up to 50K entries (1K/5K/10K/50K); skips oversized images |
- **Privacy** — whitespace-only entries are ignored; password/card/banking previews are redacted (full value still pastes); pause monitoring from the tray
+| Appearance | Dark/light follows macOS |
- **Paste plain / transforms** — ⌥-click or right-click for plain text and transforms (trim, case, JSON, …)
+| Privacy | Ignores whitespace-only entries; redacts password/card previews; pause monitoring from tray |
- **Copy only** — right-click → Copy puts content on the clipboard without auto-pasting or hiding the window
+| Transforms | Option-click or right-click: plain text, trim, case, JSON, etc. |
- **Color swatches** — hex/rgb/hsl entries (e.g. `#3366ff`) show a small color chip in the list
+| Copy only | Right-click Copy puts content on clipboard without auto-paste |
- **Launch at login** — Settings toggle registers a macOS Login Item (use the built `.app`)
+| Color swatches | Hex/rgb/hsl entries show a color chip in the list |
- **Image thumbnails** — list shows small thumbs; full images stay in the DB until paste
+| Launch at login | Settings toggle registers a macOS Login Item |
 | Image thumbnails | Small thumbs in list; full image loaded on paste |
 ## Docs
 | Doc | |
 |---|---|
-| [docs/GUIDE.md](docs/GUIDE.md) | **Install + usage guide** (the living doc — start here if you just want to use the app) |
+| [docs/GUIDE.md](docs/GUIDE.md) | Install and usage guide — start here to use the app |
 | [docs/README.md](docs/README.md) | Docs index |
 | [docs/TESTING.md](docs/TESTING.md) | Automated tests |
 | [docs/LAUNCH-AT-LOGIN.md](docs/LAUNCH-AT-LOGIN.md) | Start when Mac logs in |
@@ -48,7 +49,7 @@ A fast, native macOS clipboard manager that lives in your menu bar. Built with T
 - **Xcode Command Line Tools** — `xcode-select --install`
 - **Accessibility permission** — required for auto-paste (System Settings → Privacy & Security → Accessibility → add maCopy)
-## Quick Start
+## Quick start
 ```bash
 git clone gitea@git.levkin.ca:ilia/maCopy.git
@@ -81,7 +82,7 @@ The app will compile the Rust backend, start the Vite dev server, and launch the
 ## Development
-### Project Structure
+### Project structure
 ```
 maCopy/
@@ -127,7 +128,7 @@ maCopy/
 | `npm run lint` | TypeScript type-check |
 | `npm run check` | Lint + all tests |
-### Tech Stack
+### Tech stack
 | Layer | Technology |
 |---|---|
@@ -147,7 +148,7 @@ maCopy/
 A background Rust thread watches the macOS pasteboard **changeCount** and only reads the clipboard when it changes. Text, images (full PNG + thumbnail), and file paths are captured. List IPC returns truncated / redacted previews and image thumbnails — not multi‑MB blobs.
-### Paste & Return
+### Paste and return
 When you select an entry, maCopy writes it to the system clipboard (text or image), hides its window, waits briefly for macOS to refocus the previous app, then simulates `Cmd+V` via AppleScript. This requires Accessibility permission. Optional transforms (plain, trim, JSON, …) run before the write.
@@ -155,11 +156,11 @@ When you select an entry, maCopy writes it to the system clipboard (text or imag
 The database uses a content-synced FTS5 virtual table with triggers that automatically keep the full-text index in sync with the `clipboard_entries` table. This enables instant prefix search as you type. Opened with `journal_mode=WAL` + `synchronous=NORMAL` so the UI can read while the background poller writes, without blocking on full fsyncs.
-### Window Behavior
+### Window behavior
 The window uses `titleBarStyle: "overlay"` for native resize handles while keeping the frameless aesthetic. It's always-on-top and hides on blur (with a short delay so clicks register). Position is determined by the user's setting (near cursor via CoreGraphics, center, or a screen corner).
-## Data Storage
+## Data storage
 The SQLite database is stored at: