@tobq/boardclip 0.0.0-stage → 2.1.107

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tobi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,171 @@
-# Temporary Holding Version
+# BoardClip
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Fast cross-platform clipboard history for desktop. BoardClip runs as a tray app, opens with a global shortcut, and keeps your useful text and image clips searchable, pinnable, and quick to paste.
+
+## Install
+
+Everyday desktop builds are available from the website:
+
+[Download BoardClip](https://boardclip.app)
+
+With a package manager:
+
+```sh
+# macOS (Homebrew): the app opens with no security prompt
+brew install --cask tobq/tap/boardclip
+
+# Windows (Scoop)
+scoop bucket add tobq https://github.com/tobq/homebrew-tap
+scoop install tobq/boardclip
+
+# Any OS with Node.js 18+ (then run `boardclip`; update with `npm update -g @tobq/boardclip`)
+npm i -g @tobq/boardclip
+```
+
+Or try it without installing: `npx @tobq/boardclip`.
+
+Terminal install keeps a source checkout on your machine and reuses the same local lifecycle scripts for future updates. This path requires Git, and install/dependency updates also require npm.
+It also registers a normal launcher: `BoardClip` in the Windows Start Menu or `~/Applications/BoardClip.app` on macOS.
+
+macOS / Linux:
+
+```sh
+curl -fsSL https://boardclip.sh/install.sh | sh
+```
+
+Windows PowerShell:
+
+```powershell
+irm https://boardclip.sh/install.ps1 | iex
+```
+
+Prefer to inspect first? Open the script URL in your browser, or download it before running:
+
+```sh
+curl -fsSLO https://boardclip.sh/install.sh
+sh install.sh
+```
+
+## Update
+
+macOS / Linux:
+
+```sh
+curl -fsSL https://boardclip.sh/update.sh | sh
+```
+
+Windows PowerShell:
+
+```powershell
+irm https://boardclip.sh/update.ps1 | iex
+```
+
+Local checkout update scripts are also available:
+
+```sh
+./update.sh
+```
+
+```bat
+update.bat
+```
+
+Local update scripts are production-safe by default: they fast-forward only and
+refuse to run if tracked app files have local edits. Runtime data files are
+ignored and do not block updates. The public update commands above set
+`BOARDCLIP_UPDATE_ALLOW_DIRTY=1`, so normal installs can repair a dirty checkout
+with Git autostash. For a developer checkout, set that variable yourself only
+when you intentionally want Git to autostash local code changes.
+
+## Features
+
+- Hotkey popup: Cmd+Shift+V on macOS, Win+V on Windows.
+- Text and image history with automatic deduplication.
+- Numpad quick-paste slots 1-9 for snippets you reuse constantly.
+- Pins and groups for keeping durable clips organized, with include/exclude filters.
+- Native cloud sync through Google Drive, OneDrive, and iCloud folders.
+- Regex search, external editor support, and image export.
+- Local-first data: no hosted clipboard database or BoardClip account.
+
+## Keyboard Shortcuts
+
+| Shortcut | Action |
+| --- | --- |
+| Cmd+Shift+V / Win+V | Toggle popup |
+| Cmd+Numpad 1-9 / Win+Numpad 1-9 | Quick-paste slot |
+| 1-9 in empty search | Quick-paste slot |
+| Arrow keys | Navigate items |
+| Enter | Paste selected item |
+| Escape | Close popup |
+
+## Development
+
+Requirements:
+
+- Git
+- Node.js and npm
+
+Run from a checkout:
+
+```sh
+npm install
+npm test
+npm start
+```
+
+Build desktop binaries locally:
+
+```sh
+npm run dist
+```
+
+Platform-specific package scripts are available as `npm run dist:win`, `npm run dist:mac`, and `npm run dist:linux`. Tagged releases matching `v*` are built by GitHub Actions and attached to the GitHub release.
+
+Regenerate the shared app, installer, and site icons:
+
+```sh
+npm run sync:icons
+```
+
+Useful local scripts:
+
+```sh
+./start.sh
+./update.sh
+./kill.sh
+```
+
+```bat
+start.bat
+update.bat
+kill.bat
+```
+
+## Project Structure
+
+- `main.js`: Electron main process, tray, shortcuts, clipboard polling, sync, IPC.
+- `index.html`: single-file renderer UI.
+- `preload.js`: safe renderer API bridge.
+- `lib/clipboard-model.js`: shared pure history/pin/group merge logic.
+- `lib/cloud-accounts.js`: Google Drive, OneDrive, and iCloud folder discovery.
+- `lib/windows-hook*`: Windows low-level keyboard hook for Win+V / Win+Numpad.
+- `site/`: static landing page and remote install/update scripts.
+
+## Data
+
+Source installs store data in the app checkout. Packaged installs store data in Electron's per-user app data directory:
+
+- `clipboard-history.json`
+- `clipboard-settings.json`
+- `clipboard-images/`
+- `clipboard-text/` for large text snippets
+
+Cloud sync writes the same files into detected provider folders under `clipboard-tray/`. That folder name is retained for compatibility with earlier installs.
+
+## Contributing
+
+Issues and pull requests are welcome. Please run `npm test` before opening a PR and keep changes focused; most behavior should go through shared helpers in `lib/clipboard-model.js` instead of duplicating merge logic in UI or IPC code.
+
+## License
+
+MIT

package/bin/boardclip.js

@@ -0,0 +1,43 @@
+#!/usr/bin/env node
+// `boardclip` command of the npm package (npm i -g @tobq/boardclip, npx @tobq/boardclip):
+// starts the tray app with the Electron that npm installed beside it, detached
+// so the terminal is free again and closing it does not take the app along.
+// A second start only brings the running app's popup up (single-instance lock).
+'use strict';
+
+const { spawn } = require('child_process');
+const path = require('path');
+
+const appDir = path.join(__dirname, '..');
+const args = process.argv.slice(2);
+
+if (args.includes('--version') || args.includes('-v')) {
+  console.log(require('../package.json').version);
+  process.exit(0);
+}
+
+let electron;
+try {
+  electron = require('electron');
+} catch (error) {
+  console.error('BoardClip needs its Electron download. Reinstall with: npm i -g @tobq/boardclip');
+  process.exit(1);
+}
+
+const env = { ...process.env };
+// Set by some shells and tools; it would start Electron as plain Node.
+delete env.ELECTRON_RUN_AS_NODE;
+
+const child = spawn(electron, [appDir, ...args], {
+  cwd: appDir,
+  detached: true,
+  stdio: 'ignore',
+  windowsHide: true,
+  env,
+});
+child.on('error', (error) => {
+  console.error(`Could not start BoardClip: ${error.message}`);
+  process.exit(1);
+});
+child.unref();
+console.log('BoardClip is running in your menu bar / system tray.');

package/editor-preload.js

@@ -0,0 +1,71 @@
+const { contextBridge, ipcRenderer } = require('electron');
+
+// Bridge for the built-in editor window (editor.html). Main pushes the initial
+// text via 'editor-init'; the renderer streams drafts (every keystroke, for
+// crash-safety) and commits (idle/save/close, to write the clip), keyed by the
+// session id main assigned at open.
+let sessionId = null;
+
+contextBridge.exposeInMainWorld('editorApi', {
+  onInit: (callback) => {
+    ipcRenderer.on('editor-init', (_, init) => {
+      sessionId = init && init.sessionId;
+      callback(init || {});
+    });
+  },
+  onFind: (callback) => {
+    const listener = (_, find) => callback(find || {});
+    ipcRenderer.on('editor-find', listener);
+    return () => ipcRenderer.removeListener('editor-find', listener);
+  },
+  onConflict: (callback) => {
+    const listener = (_, conflict) => callback(conflict || {});
+    ipcRenderer.on('editor-conflict', listener);
+    return () => ipcRenderer.removeListener('editor-conflict', listener);
+  },
+  draft: (payload) => ipcRenderer.send('editor-draft', sessionId, payload),
+  // invoke (not send): the promise resolves AFTER the clip write, with the
+  // session's current (content-addressed) id — the title-bar tag strip's
+  // commit-on-add awaits it before opening the group picker.
+  commit: (payload) => ipcRenderer.invoke('editor-commit', sessionId, payload),
+  resolveConflict: (payload) => ipcRenderer.invoke('resolve-conflict', payload),
+  unifyStep: (payload) => ipcRenderer.invoke('unify-step', sessionId, payload),
+  close: () => ipcRenderer.send('editor-close', sessionId),
+  // The find bar's mode + match case, remembered per device.
+  saveFindPrefs: (prefs) => ipcRenderer.invoke('save-settings', { find_regex: !!(prefs && prefs.regex), find_case: !!(prefs && prefs.caseSensitive) }),
+  // A drag on the idle title moves this window (main's window-drag, sender only).
+  windowDrag: (phase, dx, dy) => ipcRenderer.send('window-drag', phase, dx, dy),
+  // The bar's height + resolved colours, for the native window controls.
+  windowChrome: (chrome) => ipcRenderer.send('window-chrome', chrome),
+  // Clipboard follow: while the clipboard holds this note, saves update it.
+  focused: () => ipcRenderer.send('editor-focus', sessionId),
+  copyToClipboard: (payload) => ipcRenderer.invoke('editor-copy', sessionId, payload),
+  onClipboardState: (callback) => {
+    const listener = (_, state) => callback(state || {});
+    ipcRenderer.on('editor-clipboard', listener);
+    return () => ipcRenderer.removeListener('editor-clipboard', listener);
+  },
+  // Clip menu (shared with the popup + viewer). The clip id changes on every
+  // committed edit (content-addressed), so the menu asks for the CURRENT id.
+  currentId: () => ipcRenderer.invoke('editor-current-id', sessionId),
+  state: (id) => ipcRenderer.invoke('clip-window-state', id),
+  pin: (id, rev) => ipcRenderer.invoke('pin', id, rev),
+  groupCreate: (name) => ipcRenderer.invoke('group-create', name),
+  groupAssign: (id, group, rev) => ipcRenderer.invoke('group-assign', id, group, rev),
+  numpadAssign: (id, slot, rev) => ipcRenderer.invoke('numpad-assign', id, slot, rev),
+  numpadUnassign: (slot) => ipcRenderer.invoke('numpad-unassign', slot),
+  deleteSelf: (rev) => ipcRenderer.invoke('editor-delete-clip', sessionId, rev),
+  getColorScheme: () => ipcRenderer.invoke('get-color-scheme'),
+  onColorSchemeChanged: (callback) => {
+    const listener = (_, scheme) => callback(scheme);
+    ipcRenderer.on('color-scheme-changed', listener);
+    return () => ipcRenderer.removeListener('color-scheme-changed', listener);
+  },
+  // Appearance (accent, density, corners, theme mode, this window's surface):
+  // one event whenever any of it changes - a setting, another device, the OS accent.
+  onAppearanceChanged: (callback) => {
+    const listener = (_, look) => callback(look || {});
+    ipcRenderer.on('appearance-changed', listener);
+    return () => ipcRenderer.removeListener('appearance-changed', listener);
+  },
+});

package/editor.html

@@ -0,0 +1,220 @@
+<!DOCTYPE html>
+<html><head><meta charset="utf-8"><title>Editor</title>
+<script>
+  document.documentElement.dataset.theme = matchMedia('(prefers-color-scheme: light)').matches ? 'light' : 'dark';
+</script>
+<!-- Vendored CodeMirror 5 merge view (offline, shared with the website demo);
+     powers the shared reconciliation/unify UI. Load before clipboard-ui-core. -->
+<link rel="stylesheet" href="site/shared/vendor/cm5/codemirror.css">
+<link rel="stylesheet" href="site/shared/vendor/cm5/merge.css">
+<script src="site/shared/vendor/cm5/codemirror.js"></script>
+<script src="site/shared/vendor/cm5/diff-match-patch.js"></script>
+<script src="site/shared/vendor/cm5/merge.js"></script>
+<link rel="stylesheet" href="site/shared/clipboard-popup.css">
+<link rel="stylesheet" href="site/shared/clipboard-window.css">
+<style>
+  /* Editor window shell only; the editor itself + tokens come from the shared
+     clipboard-popup.css + Core.createEditor (single source with the demo), the
+     window base (reset, font, background, glass scrim) from clipboard-window.css. */
+  #editorHost { height:100%; }
+</style></head><body>
+<div id="editorHost"></div>
+<div class="toast" id="toast">Copied</div>
+<script src="site/shared/clip-search.js"></script>
+<script src="site/shared/clipboard-ui-core.js"></script>
+<script>
+const Core = window.BoardClipCore;
+const host = document.getElementById('editorHost');
+
+// Theme: follow the app's theme_mode setting + live system changes, exactly
+// like the popup (Core.applyTheme on <html>).
+let themeMode = 'system';
+let systemDark = matchMedia('(prefers-color-scheme: dark)').matches;
+function refreshTheme() { Core.applyTheme(document.documentElement, themeMode, systemDark); }
+if (window.editorApi.getColorScheme) window.editorApi.getColorScheme().then((s) => { systemDark = s !== 'light'; refreshTheme(); }).catch(() => {});
+if (window.editorApi.onColorSchemeChanged) window.editorApi.onColorSchemeChanged((s) => { systemDark = s !== 'light'; refreshTheme(); });
+// Later appearance changes (a setting here or on another device, the OS
+// accent, the glass scope) arrive as the same payload as init.
+if (window.editorApi.onAppearanceChanged) window.editorApi.onAppearanceChanged((look) => {
+  if (look.themeMode) { themeMode = (look.themeMode === 'light' || look.themeMode === 'dark') ? look.themeMode : 'system'; refreshTheme(); }
+  Core.applyAppearance(document.documentElement, look);
+});
+
+let editor = null;
+let reconcileView = null;
+let windowControls = null; // Core.attachWindowControls, set up on init
+let toastTimer = null;
+function showToast(message) {
+  const toast = document.getElementById('toast');
+  if (!toast) return;
+  toast.textContent = message || 'Copied';
+  toast.classList.add('show');
+  clearTimeout(toastTimer);
+  toastTimer = setTimeout(() => toast.classList.remove('show'), 1200);
+}
+
+// --- Shared clip menu (pin/group/numpad/title/delete), same as the popup rows
+// and the image viewer. Backed by a light state snapshot fetched right before
+// the menu opens (the clip id changes on every committed edit, so the CURRENT
+// id comes from main at open time too). context 'editor' hides "Open in editor".
+let menuState = { item: null, items: [], groups: [], aiGroup: 'AI' };
+let menuClipId = null;
+// Title-bar tag strip: re-render from the CURRENT clip (the id is content-
+// addressed, so it changes on every committed text edit — always re-query).
+// A new note that hasn't committed yet shows just the + (commit-on-add).
+async function refreshTags() {
+  if (!editor) return;
+  const id = await window.editorApi.currentId();
+  if (!id) { editor.setTags(null, { allowAdd: true }); return; }
+  menuClipId = id;
+  menuState = await window.editorApi.state(id);
+  editor.setTags(menuState.item, { allowAdd: true });
+}
+// Menu mutations send the rev from the state snapshot fetched when the menu
+// opened; a stale one is refused. (Text commits keep their own base-text
+// conflict handling, which forks rather than losing typed work.)
+const clipRevOf = (id) => { const it = menuState.items.find((x) => Core.itemId(x) === id); return it ? it.rev : undefined; };
+const revGuard = (run, fallback) => Core.guardRevision(run, { toast: showToast, refresh: () => refreshTags(), fallback });
+const menuAdapter = {
+  menuContext: 'editor',
+  itemById: (id) => menuState.items.find((it) => Core.itemId(it) === id) || null,
+  allItems: () => menuState.items,
+  groupNames: () => menuState.groups,
+  numpadMap: () => Core.numpadMap(menuState.items),
+  protectedGroups: () => new Set([menuState.aiGroup]),
+  pin: (id) => revGuard(() => window.editorApi.pin(id, clipRevOf(id)), false),
+  toggleGroup: (id, group) => revGuard(() => window.editorApi.groupAssign(id, group, clipRevOf(id)), false),
+  createGroup: (name) => window.editorApi.groupCreate(name),
+  numpadAssign: (id, slot) => revGuard(() => window.editorApi.numpadAssign(id, slot, clipRevOf(id)), false),
+  numpadUnassign: (slot) => window.editorApi.numpadUnassign(slot),
+  // The editor's title INPUT is authoritative (it rides every commit); a menu
+  // rename would be reverted by the next commit if it only touched the clip.
+  // Set the input + commit through the session instead — one write path.
+  setClipTitle: (_id, title) => { if (editor) { editor.setTitle(title); editor.commit(); } },
+  // The clip menu's "Revert to original": the editor's own revert (one path).
+  revertClip: () => { if (editor) editor.revert(); },
+  // Delete closes the window; main suppresses the close-commit so the draft
+  // can't resurrect the clip.
+  deleteClips: async (ids) => revGuard(async () => { await window.editorApi.deleteSelf(clipRevOf((ids && ids[0]) || menuClipId)); return []; }, []),
+  // Commit-on-add for the tag strip's + on a new note: force-commit the draft
+  // through the ONE existing write path, then re-query the fresh clip id.
+  ensureClipId: async () => {
+    if (editor) await Promise.resolve(editor.commit());
+    const id = await window.editorApi.currentId();
+    if (id) await refreshTags(); // picker needs the fresh item in menuState
+    return id || null;
+  },
+  toast: (message) => showToast(message),
+  render: () => {},
+  refresh: async () => { await refreshTags(); },
+};
+const menuController = Core.createClipController(menuAdapter);
+document.addEventListener('click', (e) => menuController.onClick(e));
+async function openClipMenu(x, y) {
+  menuClipId = await window.editorApi.currentId();
+  if (!menuClipId) return; // new note not committed yet — no clip to act on
+  menuState = await window.editorApi.state(menuClipId);
+  menuController.openClipMenu(menuClipId, x, y);
+}
+
+window.editorApi.onInit((init) => {
+  themeMode = (init.themeMode === 'light' || init.themeMode === 'dark') ? init.themeMode : 'system';
+  refreshTheme();
+  // The appearance payload (this window's surface, the accent colour, density,
+  // corners), through the one applier every window uses.
+  Core.applyAppearance(document.documentElement, init);
+  // The OS's own window controls: the bar reserves their room and reports its
+  // colours, so the caption buttons match it (main's setTitleBarOverlay).
+  if (!windowControls) windowControls = Core.attachWindowControls(init.windowControls, window.editorApi.windowChrome);
+  host.innerHTML = '';
+  reconcileView = null;
+  editor = Core.createEditor({
+    initialText: init.text || '',
+    initialTitle: init.noteTitle || '',
+    initialFind: init.find || '',
+    initialFindRegex: init.findRegex,
+    findPrefs: init.findPrefs,
+    saveFindPrefs: (prefs) => window.editorApi.saveFindPrefs && window.editorApi.saveFindPrefs(prefs),
+    initialFocusTitle: !!init.focusTitle,
+    nativeControls: true,
+    windowDrag: window.editorApi.windowDrag,
+    toastEl: document.getElementById('toast'), // Revert to original offers Undo here
+    onInput: (payload) => window.editorApi.draft(payload),     // live crash-safe draft, every keystroke
+    // idle / Ctrl+S / close -> write the clip. The commit changes the content-
+    // addressed id, so refresh the title-bar tag strip once the write lands
+    // (returned promise also lets the strip's commit-on-add await the write).
+    onCommit: (payload) => window.editorApi.commit(payload).then((r) => { refreshTags(); return r; }),
+    onClose: () => window.editorApi.close(),
+    // While the clipboard holds this note, every save also updates it (main's
+    // clipboard follower); the footer shows that, or a Copy button to start it.
+    clipboard: window.editorApi.copyToClipboard ? {
+      following: !!init.clipboardFollowing,
+      onCopy: (payload) => window.editorApi.copyToClipboard(payload),
+    } : null,
+    // "..." in the editor chrome -> the shared clip menu (existing clips only;
+    // a brand-new note has no clip until its first commit).
+    ...(init.isNew ? {} : { onMenu: (x, y) => openClipMenu(x, y) }),
+  });
+  host.appendChild(editor.el);
+  windowControls.refresh();
+  editor.focus();
+  refreshTags();
+});
+
+// Clipboard follow: main pushes start/stop; regaining focus asks main to
+// re-check (the user may have copied this note, or something else, meanwhile).
+if (window.editorApi.onClipboardState) window.editorApi.onClipboardState((state) => { if (editor) editor.setClipboardState(state); });
+window.addEventListener('focus', () => { if (editor && window.editorApi.focused) window.editorApi.focused(); });
+// Right-click in the editor chrome (bar/foot — not the text area, where the
+// native text menu belongs) opens the same clip menu.
+document.addEventListener('contextmenu', (e) => {
+  if (e.target.closest('.bc-editor-area, .bc-bar-title, .bc-find-input, input, textarea')) return;
+  if (!editor || reconcileView) return;
+  e.preventDefault();
+  openClipMenu(e.clientX, e.clientY);
+});
+
+if (window.editorApi.onFind) {
+  window.editorApi.onFind((find) => {
+    if (!editor || !find) return;
+    if (find.focusTitle && editor.focusTitle) editor.focusTitle();
+    else if (find.query) editor.openFind(find.query, find.findRegex);
+  });
+}
+
+if (window.editorApi.onConflict) {
+  // Mounts the SHARED reconciliation view for both a sync conflict (resolve +
+  // close) and a Unify session (record.unify: fold each step, only close on the
+  // final merge). One view, two drivers.
+  function mountReconcile(record) {
+    host.innerHTML = '';
+    editor = null;
+    reconcileView = Core.createReconciliationView({
+      record,
+      windowDrag: window.editorApi.windowDrag,
+      onResolve: async (resolution) => {
+        if (record.unify && window.editorApi.unifyStep) {
+          const next = await window.editorApi.unifyStep(resolution);
+          if (next && next.done === false && next.nextRecord) { mountReconcile(next.nextRecord); return; }
+          window.editorApi.close();
+          return;
+        }
+        await window.editorApi.resolveConflict(resolution);
+        window.editorApi.close();
+      },
+      onClose: () => window.editorApi.close(),
+      nativeControls: true,
+    });
+    host.appendChild(reconcileView.el);
+    if (windowControls) windowControls.refresh();
+  }
+  window.editorApi.onConflict((record) => {
+    if (!record || !record.id) return;
+    mountReconcile(record);
+  });
+}
+
+// Commit any pending edit if the window is closing out from under us.
+window.addEventListener('beforeunload', () => { if (editor) editor.commit(); });
+</script>
+</body></html>