v1.5.2 — heartbeat instance lock (dual-install safety)

Defensive hotfix for users who ended up with two Clipboard Watcher instances installed simultaneously.

The bug

If you install v1 and then v2 of the plugin via Eagle's .eagleplugin flow, Eagle does not automatically deduplicate by manifest.id. Both serviceMode instances start, both poll the clipboard, and both call eagle.item.addFromPath. Eagle internally rejects the second call as a duplicate and emits a "duplicate image" warning every time you copy an image.

What v1.5.2 does

Adds a heartbeat lock via localStorage:

1. Each instance generates a random instanceId on load
2. Each poll cycle writes clipboardWatcher.heartbeat = { instanceId, ts, version }
3. Before importing, each poll reads the heartbeat. If it shows a different instanceId written less than 3 seconds ago, the instance suspends imports and surfaces this banner:

   检测到另一个 Clipboard Watcher（v{version}）也在运行。请在 Eagle 插件管理中删掉旧版本，保留一个。

4. Once you remove the older instance via Eagle → Plugins → Manage, the surviving instance's next poll sees no fresh heartbeat from anyone else and automatically resumes within 3 seconds.

Assumption: Eagle shares the localStorage origin between same-id plugin instances. If it doesn't, this mechanism degrades to a harmless no-op — each instance only ever sees its own heartbeat. The Plugin Manager cleanup remains the canonical fix in either case.

Recommended action

1. Install v1.5.2 over your current version (settings persist).
2. Open Eagle → Plugins → Manage Plugins and check the count.
3. If you see two Clipboard Watcher entries, delete the older one.
4. If you see one entry but the panel still warns about a second instance, please open an issue with the Eagle log panel output.

Full notes: docs/CHANGELOG.md

v1.5.1 — macOS fullscreen hotfix

macOS hotfix. Recommended upgrade for anyone running Eagle in full-screen Space on macOS.

Fixed

• Settings panel inheriting macOS full-screen state, and black screen flash on panel close.
  • Root cause: the manifest did not declare fullscreenable, so Eagle used the default true. macOS therefore treated the plugin window as fullscreen-capable, and when Eagle was running in a full-screen Space, the plugin window joined that Space — triggering the system's fullscreen transition animation on open/close (the black flash).
  • Fix: explicit fullscreenable: false plus defensive maximizable: false in manifest.main. Combined with existing maxWidth: 460 / maxHeight: 640, the window now stays a small floating panel that does not animate into a fullscreen Space.

No JS / runtime / config changes. Direct overinstall over v1.5.0 is safe; settings persist.

Full notes: docs/CHANGELOG.md

v1.5.0 — bundle hotfix (#2) + name template (F13)

Important release. v1.3.0 and v1.4.0 users — please upgrade.

🚨 Fixed

[#2] Empty panel since v1.3.0

The v1.3.0 modular refactor introduced a regression: in Eagle 4.x, relative require('./lib/xxx') calls in scripts loaded via <script src> throw, so window.ClipboardWatcher was never set up and the UI rendered as a blank panel with only "未运行" (HTML-residue text) visible.

Fix: new local bundler build/bundle.js concatenates all js/lib/*.js + js/plugin.js + js/ui.js in dependency order into a single js/bundle.js. At runtime, index.html loads only this one file — no require calls in the webview.

• Source code stays modular (developer experience preserved)
• Shipping artifact is a single file (works around the Eagle webview limitation)
• npm run build regenerates the bundle; npm run pack builds before zipping
• Pack output dropped from 30.7 KB → 25.3 KB (deduplicated)

✨ Added

Customizable item name template (F13)

You can now decide how saved items are named. Default template {source} {dims} {timestamp} preserves v1.4 behavior.

Available tokens:

Token	Means
{source}	Screenshot or Clipboard
{dims}	1920x1080 (empty when unknown)
{timestamp}	2026-06-03 02:30:00
{date}	2026-06-03
{time}	02:30:00
{hostname}	your machine name
{count}	today's save count (after this save)
{lifetime}	lifetime count (after this save)

• Lives in Advanced settings with live preview + "Restore default" link
• Multi-file batch imports do not use the template — they keep using the original filename
• Empty template falls back to the default automatically

Upgrade

Just install .eagleplugin over your existing version. Your settings persist in localStorage and are not lost.

If you still see a blank panel after upgrading, please leave a comment in #2 with any [bundle]-prefixed errors from the Eagle log panel.

Full notes: docs/CHANGELOG.md

v1.4.0 — multi-folder routing + lifetime count + full EN i18n

First wave of dividends from the v1.3.0 modular refactor. Three features, each touching only 2–3 lib modules — proving the architecture boundaries are working.

New

📁 Per-source folder routing

Optional: have screenshots, copied images, and multi-file copies land in different Eagle folders.

• 4 folder fields in config: folderId (main, required) plus folderIdScreenshot / folderIdClipboard / folderIdFiles (each optional)
• Unset = falls back to the main folder
• Advanced settings has 3 new selects at the bottom with "use main folder" as the default
• On enable, the main folder is backfilled synchronously; routed folders backfill in the background

Default behavior is unchanged: all images still go to the main folder unless you explicitly route a source elsewhere.

📊 Lifetime save count

Now persists across sessions. Status line shows Saved today: N · M total once you've saved anything.

🌐 Full English translation

All 67 i18n strings now have an English version. Locale auto-detects via navigator.language (zh / en). The plugin will speak English on English-language systems, Chinese on Chinese ones.

Known trade-off

macOS system screenshot shortcut (Cmd+Shift+Ctrl+4, not the in-panel button) is classified as clipboard source, so it'll land in the clipboard-routed folder if you set one. Distinguishing it from regular clipboard copies would require Eagle to expose a clipboard owner API, which isn't public.

Install

Download eagle-clipboard-watcher.eagleplugin below and double-click to install.

Repo is private — Release download requires GitHub login with read access.

Full notes: docs/CHANGELOG.md

v1.3.0 — modular refactor + i18n bootstrap

Architecture refactor release. Zero behavior change vs v1.2.1.

User-facing functionality is identical to v1.2.1. This release is groundwork for future feature development.

What changed

• js/plugin.js split from a single 1,100-line file into 12 focused lib/ modules + a 150-line orchestrator:
  • constants / utils / state / config / i18n / theme / folders / clipboard / import / screenshot / notification / poll
• Every UI string now goes through t('namespace.key') — i18n table set up for future English distribution (currently zh-only)
• State is centralized with controlled mutators; no more scattered state.xxx = ... writes
• Error codes promoted from bare strings to a central ERROR_CODES enum
• HTML static labels extracted to id-based shells, populated by renderStaticLabels() from i18n table
• JSDoc typedefs added for state shape

Why this exists

Adding new features (custom naming templates, multi-folder routing, OCR auto-tagging) requires clear module boundaries. The previous single-file structure made every change feel risky.

Verification

If anything breaks, please:

1. Reproduce on v1.2.1 to determine whether it's a pre-existing bug or a regression
2. Open a Bug Report noting both versions tested

Install

Download eagle-clipboard-watcher.eagleplugin below and double-click to install. Same install flow as previous versions.

Repo is private — Release download requires GitHub login with read access.

Full notes: docs/CHANGELOG.md

v1.2.1 — hotfix #1: skip system preview icons on file copy

Hotfix for #1.

Fixed

• No longer imports the system-generated preview icon when you copy a file / folder / PDF in Finder or Explorer.
  • When you Cmd+C / Ctrl+C a file (especially a folder or PDF), macOS / Windows places both a file URL and an auto-generated preview thumbnail in the clipboard.
  • v1.2.0 saw the image/* slot and imported the icon — never what the user wanted.
  • v1.2.1 checks for a file URL first; when present, the image slot is treated as a system-generated thumbnail and skipped. Only the multi-file path runs (which itself filters to image extensions), and only if you opted into multi-file copy.
  • Net effect: copying a PDF / folder / non-image file is now completely silent — nothing lands in Eagle.

How to verify

After installing v1.2.1:

1. Cmd+C on a folder in Finder → nothing should appear in Eagle
2. Cmd+C on a PDF → nothing should appear in Eagle
3. Cmd+C on a .txt / .docx → nothing should appear in Eagle
4. Regular screenshot / browser image copy → still saves as before
5. With "save multi-file copy" toggled on: Cmd+C on multiple images → all imported; Cmd+C on a folder → still nothing

Install

Download eagle-clipboard-watcher.eagleplugin below, double-click to install.

Repo is private — Release download requires GitHub login with read access.

Full notes: docs/CHANGELOG.md

v1.2.0 — theme fix + Linux multi-file

Patch + cross-platform completion. No breaking changes.

Fixed

• LIGHTGRAY theme was misclassified as dark — the old detection used a /DARK|GRAY|BLUE|PURPLE/i regex; LIGHTGRAY contains the substring GRAY, so the panel rendered with dark CSS variables on a light Eagle theme (text became hard to read). Replaced with exact Set matching: dark themes are now strictly GRAY / DARK / BLUE / PURPLE. LIGHT / LIGHTGRAY / Auto render with light vars.

Added

• Linux multi-file clipboard import (previously macOS + Windows only)
  • Wayland: wl-paste --type text/uri-list
  • X11: xclip -selection clipboard -t text/uri-list -o
  • Auto-detects \$WAYLAND_DISPLAY for ordering, falls back if either tool is missing
  • text/uri-list parsing strips file:// and URL-decodes
  • Silently no-ops when neither tool is installed

Changed

• UI hint for the multi-file toggle now mentions Linux explicitly

Install

Download eagle-clipboard-watcher.eagleplugin below and double-click in Eagle.

Repository remains private — Release download requires GitHub login with read access.

Full notes: docs/CHANGELOG.md

v1.1.0 — click to open + failure notifications + issue templates

Polish release on top of v1.0.0. No breaking changes.

New

• Click "Recent saves" → opens the item in Eagle
  • Uses eagle.item.open(itemId) — addFromPath return value is now captured and stored alongside each recent entry
  • Cards have hover feedback + cursor pointer
  • Supported by single-image clipboard, screenshot button, and multi-file batch paths
• Failure notifications — when addFromPath / temp file write / multi-file batch fails, you also get a system notification (shares the same "send system notification on save" toggle)
• GitHub Issue templates — bug + feature templates with platform/version/repro/log fields. Issues now enabled on this repo.

Changed

• Notification phrasing unified with the UI's "saved" wording

Install

Same as v1.0.0 — download eagle-clipboard-watcher.eagleplugin below and double-click to install in Eagle.

Repository is private: this Release and asset download require GitHub login with read access to the repo.

Full notes: docs/CHANGELOG.md

v1.0.0 — first stable release

First stable release of Eagle Clipboard Watcher.

Install

Drop the .eagleplugin below into Eagle (drag-and-drop on the Eagle window, or double-click the file).

Heads up: this repository is currently private, so this Release page and the asset download are only visible if you are signed in with a collaborator account. For public distribution, wait for Eagle Plugin Center listing.

What's in it

Covers PRD F1–F11 (see docs/prd.md):

• Clipboard auto-import — copy any image and it appears in your chosen Eagle folder within 1 second
• Take Screenshot button (macOS) — screencapture -ic selection → clipboard → Eagle
• Mixed content import — image + text rich clipboard, image part auto-saved (toggle to opt out)
• Multi-file batch — Finder / Explorer multi-select Cmd/Ctrl+C, all imported (opt-in)
• Per-folder dedup — skip images already in target folder, with on-startup backfill from existing Eagle items
• Adaptive polling — macOS 14+ Sonoma "Pasted from Eagle" banner mitigation: slows to 5s when clipboard image is idle, snaps back on change
• User-perspective UI — all settings phrased for users, not developers
• 100% local — zero network, zero telemetry, zero analytics

Tech / privacy

• Uses eagle.clipboard, eagle.item.addFromPath, eagle.folder.getAll, eagle.notification, eagle.app.theme
• Multi-file copy via osascript (macOS) / PowerShell (Windows), 2s timeout, 50-file cap
• Config stored in localStorage (sandboxed per plugin)
• Temporary image files in os.tmpdir()/eagle-cw/, auto-deleted after import
• See docs/decisions.md for the 11 ADRs behind the design

Milestones in this release

M1 → M2 → M2.1 → M2.2 → M3 → M3.1 → M4 → M5 → M6 → M7

Full notes: docs/CHANGELOG.md

License

PolyForm Noncommercial 1.0.0 — source-available, non-commercial, attribution required. For commercial licensing, contact lc4t0.0@gmail.com.