@tobq/boardclip 0.0.0-stage → 2.1.107

package/lib/macos-hotkey.js

@@ -0,0 +1,297 @@
+'use strict';
+
+// macOS Carbon hotkeys cover shortcut paths where Electron's globalShortcut is
+// incomplete or flaky: Globe/Fn popup shortcuts and numeric quick-paste slots.
+// Unlike a Quartz event tap, this should not require Input Monitoring.
+
+const koffi = require('koffi');
+
+const MOD_COMMAND = 1 << 8;
+const MOD_SHIFT = 1 << 9;
+const MOD_ALT = 1 << 11;
+const MOD_CONTROL = 1 << 12;
+const MOD_FN = 1 << 17;
+
+const KEY_CODE_BY_NAME = {
+  A: 0x00, S: 0x01, D: 0x02, F: 0x03, H: 0x04, G: 0x05, Z: 0x06, X: 0x07,
+  C: 0x08, V: 0x09, B: 0x0B, Q: 0x0C, W: 0x0D, E: 0x0E, R: 0x0F, Y: 0x10,
+  T: 0x11, 1: 0x12, 2: 0x13, 3: 0x14, 4: 0x15, 6: 0x16, 5: 0x17,
+  '=': 0x18, 9: 0x19, 7: 0x1A, Minus: 0x1B, 8: 0x1C, 0: 0x1D, ']': 0x1E,
+  O: 0x1F, U: 0x20, '[': 0x21, I: 0x22, P: 0x23, L: 0x25, J: 0x26,
+  "'": 0x27, K: 0x28, ';': 0x29, Backslash: 0x2A, ',': 0x2B, '/': 0x2C,
+  N: 0x2D, M: 0x2E, '.': 0x2F, '`': 0x32,
+  Enter: 0x24, Tab: 0x30, Space: 0x31, Backspace: 0x33, Escape: 0x35,
+  Delete: 0x75, Home: 0x73, End: 0x77, PageUp: 0x74, PageDown: 0x79,
+  Left: 0x7B, Right: 0x7C, Down: 0x7D, Up: 0x7E,
+  F1: 0x7A, F2: 0x78, F3: 0x63, F4: 0x76, F5: 0x60, F6: 0x61,
+  F7: 0x62, F8: 0x64, F9: 0x65, F10: 0x6D, F11: 0x67, F12: 0x6F,
+  F13: 0x69, F14: 0x6B, F15: 0x71, F16: 0x6A, F17: 0x40, F18: 0x4F,
+  F19: 0x50, F20: 0x5A,
+  num0: 0x52, num1: 0x53, num2: 0x54, num3: 0x55, num4: 0x56,
+  num5: 0x57, num6: 0x58, num7: 0x59, num8: 0x5B, num9: 0x5C,
+};
+
+let carbon = null;
+let target = null;
+let handlerCallback = null;
+let handlerRef = null;
+const hotKeyRefs = new Map();
+const handlers = new Map();
+const DEFAULT_NAMESPACE = 'default';
+const QUICK_PASTE_NAMESPACE = 'quickPaste';
+
+function fourCharCode(value) {
+  return (
+    (value.charCodeAt(0) << 24) |
+    (value.charCodeAt(1) << 16) |
+    (value.charCodeAt(2) << 8) |
+    value.charCodeAt(3)
+  ) >>> 0;
+}
+
+const EventHotKeyID = koffi.struct('EventHotKeyID', {
+  signature: 'uint32',
+  id: 'uint32',
+});
+
+const EventTypeSpec = koffi.struct('EventTypeSpec', {
+  eventClass: 'uint32',
+  eventKind: 'uint32',
+});
+
+function loadCarbon() {
+  if (carbon) return;
+  carbon = koffi.load('/System/Library/Frameworks/Carbon.framework/Carbon');
+  const EventHandlerProc = koffi.proto('int EventHandlerProc(void *nextHandler, void *event, void *userData)');
+
+  carbon.GetApplicationEventTarget = carbon.func('void *GetApplicationEventTarget()');
+  carbon.InstallEventHandler = carbon.func(
+    'int InstallEventHandler(void *target, EventHandlerProc *handler, uint32 numTypes, EventTypeSpec *list, void *userData, _Out_ void **outHandlerRef)'
+  );
+  carbon.RemoveEventHandler = carbon.func('int RemoveEventHandler(void *handlerRef)');
+  carbon.RegisterEventHotKey = carbon.func(
+    'int RegisterEventHotKey(uint32 code, uint32 modifiers, EventHotKeyID hotKeyID, void *target, uint32 options, _Out_ void **outRef)'
+  );
+  carbon.UnregisterEventHotKey = carbon.func('int UnregisterEventHotKey(void *hotKey)');
+  carbon.GetCurrentKeyModifiers = carbon.func('uint32 GetCurrentKeyModifiers()');
+  carbon.GetEventParameter = carbon.func(
+    'int GetEventParameter(void *event, uint32 name, uint32 desiredType, void *outActualType, uint32 bufferSize, void *outActualSize, _Out_ EventHotKeyID *outData)'
+  );
+
+  target = carbon.GetApplicationEventTarget();
+  handlerCallback = koffi.register((_nextHandler, event) => {
+    const hotKeyID = {};
+    try {
+      const status = carbon.GetEventParameter(
+        event,
+        fourCharCode('----'),
+        fourCharCode('hkid'),
+        null,
+        koffi.sizeof(EventHotKeyID),
+        null,
+        hotKeyID
+      );
+      const handler = status === 0 ? handlers.get(hotKeyID.id) : null;
+      if (handler) handler();
+    } catch (err) { console.error('[macos-hotkey] onPressed:', err); }
+    return 0;
+  }, koffi.pointer(EventHandlerProc));
+}
+
+function normalizeShortcutPart(part) {
+  const value = String(part || '').trim();
+  const lower = value.toLowerCase();
+  if (lower === 'globe' || lower === 'function') return 'Fn';
+  if (lower === 'cmd') return 'Command';
+  if (lower === 'ctrl') return 'Control';
+  if (lower === 'option') return 'Alt';
+  if (lower === 'super' || lower === 'meta') return 'Command';
+  if (lower === 'return') return 'Enter';
+  if (lower === 'esc') return 'Escape';
+  if (lower === 'plus') return 'Plus';
+  if (lower === 'minus') return 'Minus';
+  if (/^num[0-9]$/i.test(value)) return value.toLowerCase();
+  if (/^f([1-9]|1[0-9]|20)$/i.test(value)) return value.toUpperCase();
+  if (value.length === 1 && /[a-z]/i.test(value)) return value.toUpperCase();
+  return value;
+}
+
+function modifierMask(part) {
+  switch (normalizeShortcutPart(part)) {
+    case 'Command':
+    case 'CommandOrControl':
+    case 'CommandOrCtrl':
+    case 'CmdOrCtrl':
+      return MOD_COMMAND;
+    case 'Control': return MOD_CONTROL;
+    case 'Alt': return MOD_ALT;
+    case 'Shift': return MOD_SHIFT;
+    case 'Fn': return MOD_FN;
+    default: return 0;
+  }
+}
+
+function usesFn(shortcut) {
+  return String(shortcut || '').split('+').some(part => normalizeShortcutPart(part) === 'Fn');
+}
+
+function parseShortcut(shortcut) {
+  const parts = String(shortcut || '').split('+').map(normalizeShortcutPart).filter(Boolean);
+  let modifiers = 0;
+  let keyName = '';
+  for (const part of parts) {
+    const mask = modifierMask(part);
+    if (mask) modifiers |= mask;
+    else keyName = part;
+  }
+  if (keyName === 'Plus') keyName = '=';
+  const keyCode = KEY_CODE_BY_NAME[keyName];
+  if (typeof keyCode !== 'number') return null;
+  return { keyCode, modifiers };
+}
+
+function installHandler() {
+  if (handlerRef) return { ok: true };
+  const out = [null];
+  const status = carbon.InstallEventHandler(target, handlerCallback, 1, [{
+    eventClass: fourCharCode('keyb'),
+    eventKind: 5,
+  }], null, out);
+  if (status !== 0) return { ok: false, error: `Could not install macOS hotkey handler (${status}).` };
+  handlerRef = out[0];
+  return { ok: true };
+}
+
+function unregisterHotKey(id) {
+  const entry = hotKeyRefs.get(id);
+  if (entry && entry.ref) {
+    try { carbon.UnregisterEventHotKey(entry.ref); } catch {}
+  }
+  hotKeyRefs.delete(id);
+  handlers.delete(id);
+}
+
+function clearNamespace(namespace = DEFAULT_NAMESPACE) {
+  for (const [id, entry] of [...hotKeyRefs.entries()]) {
+    if (entry.namespace === namespace) unregisterHotKey(id);
+  }
+}
+
+function clearRuntimeShortcut() {
+  clearNamespace(DEFAULT_NAMESPACE);
+}
+
+function clearQuickPasteShortcuts() {
+  clearNamespace(QUICK_PASTE_NAMESPACE);
+}
+
+function registerParsedHotKey({ parsed, id, namespace, handler, signature = 'BChk' }) {
+  loadCarbon();
+  const handlerResult = installHandler();
+  if (!handlerResult.ok) return handlerResult;
+
+  unregisterHotKey(id);
+  const out = [null];
+  const status = carbon.RegisterEventHotKey(parsed.keyCode, parsed.modifiers, {
+    signature: fourCharCode(signature),
+    id,
+  }, target, 0, out);
+
+  if (status !== 0) {
+    const error = status === -9878
+      ? 'Shortcut is already in use.'
+      : `Could not register macOS shortcut (${status}).`;
+    return { ok: false, error };
+  }
+
+  hotKeyRefs.set(id, { ref: out[0], namespace });
+  handlers.set(id, handler);
+  return { ok: true };
+}
+
+function install({ shortcut, onPressed: handler }) {
+  if (process.platform !== 'darwin') return { ok: false, error: 'macOS hotkeys are only available on macOS.' };
+  const parsed = parseShortcut(shortcut);
+  if (!parsed) return { ok: false, error: `Could not parse ${shortcut}.` };
+
+  clearRuntimeShortcut();
+  return registerParsedHotKey({ parsed, id: 1, namespace: DEFAULT_NAMESPACE, handler });
+}
+
+function shortcutForSlot(shortcut, slot) {
+  const parts = String(shortcut || '').split('+').map(normalizeShortcutPart).filter(Boolean);
+  if (!parts.length) return '';
+  parts[parts.length - 1] = String(slot);
+  return parts.join('+');
+}
+
+function installQuickPaste({ shortcut, onSlot }) {
+  if (process.platform !== 'darwin') return { ok: false, error: 'macOS hotkeys are only available on macOS.' };
+  clearQuickPasteShortcuts();
+  for (let slot = 1; slot <= 9; slot++) {
+    const slotShortcut = shortcutForSlot(shortcut, slot);
+    const parsed = parseShortcut(slotShortcut);
+    if (!parsed) {
+      clearQuickPasteShortcuts();
+      return { ok: false, error: `Could not parse ${slotShortcut}.` };
+    }
+    const result = registerParsedHotKey({
+      parsed,
+      id: 100 + slot,
+      namespace: QUICK_PASTE_NAMESPACE,
+      handler: () => onSlot(slot),
+      signature: 'BCqp',
+    });
+    if (!result.ok) {
+      clearQuickPasteShortcuts();
+      return result;
+    }
+  }
+  return { ok: true };
+}
+
+function currentModifierParts() {
+  if (process.platform !== 'darwin') return [];
+  loadCarbon();
+  const modifiers = carbon.GetCurrentKeyModifiers();
+  const parts = [];
+  if (modifiers & MOD_FN) parts.push('Fn');
+  if (modifiers & MOD_COMMAND) parts.push('Command');
+  if (modifiers & MOD_CONTROL) parts.push('Control');
+  if (modifiers & MOD_ALT) parts.push('Alt');
+  if (modifiers & MOD_SHIFT) parts.push('Shift');
+  return parts;
+}
+
+function resolveShortcutFromCurrentModifiers(shortcut) {
+  const parts = String(shortcut || '').split('+').map(normalizeShortcutPart).filter(Boolean);
+  const keyName = parts.reverse().find(part => !modifierMask(part));
+  if (!keyName) return shortcut;
+  const modifiers = currentModifierParts();
+  return modifiers.length ? [...modifiers, keyName].join('+') : shortcut;
+}
+
+function uninstall() {
+  clearNamespace(DEFAULT_NAMESPACE);
+  clearNamespace(QUICK_PASTE_NAMESPACE);
+  if (handlerRef && carbon) {
+    try { carbon.RemoveEventHandler(handlerRef); } catch {}
+  }
+  handlerRef = null;
+  if (handlerCallback) {
+    try { koffi.unregister(handlerCallback); } catch {}
+  }
+  handlerCallback = null;
+}
+
+module.exports = {
+  install,
+  clearRuntimeShortcut,
+  installQuickPaste,
+  clearQuickPasteShortcuts,
+  currentModifierParts,
+  resolveShortcutFromCurrentModifiers,
+  uninstall,
+  usesFn,
+  parseShortcut,
+};

package/lib/macos-paste.js

@@ -0,0 +1,112 @@
+'use strict';
+
+if (process.platform !== 'darwin') {
+  module.exports = {
+    sendCommandV() { return { ok: true }; },
+    typeText() { return { ok: false, chars: 0 }; },
+  };
+  return;
+}
+
+const koffi = require('koffi');
+
+let coreGraphics = null;
+let coreFoundation = null;
+
+const KEY_V = 0x09;
+const KEY_COMMAND = 0x37;
+const kCGHIDEventTap = 0;
+const kCGEventFlagMaskCommand = 1 << 20;
+
+function loadFrameworks() {
+  if (coreGraphics) return;
+  coreGraphics = koffi.load('/System/Library/Frameworks/CoreGraphics.framework/CoreGraphics');
+  coreFoundation = koffi.load('/System/Library/Frameworks/CoreFoundation.framework/CoreFoundation');
+
+  coreGraphics.CGEventCreateKeyboardEvent = coreGraphics.func(
+    'void *CGEventCreateKeyboardEvent(void *source, uint16 virtualKey, bool keyDown)'
+  );
+  coreGraphics.CGEventSetFlags = coreGraphics.func(
+    'void CGEventSetFlags(void *event, uint64 flags)'
+  );
+  coreGraphics.CGEventPost = coreGraphics.func(
+    'void CGEventPost(uint32 tap, void *event)'
+  );
+  // Sets the Unicode payload of a keyboard event: posting it inserts the exact
+  // string as text (layout-independent), the macOS analogue of Windows'
+  // KEYEVENTF_UNICODE. UniChar is uint16, so we pass a UTF-16 code-unit buffer.
+  coreGraphics.CGEventKeyboardSetUnicodeString = coreGraphics.func(
+    'void CGEventKeyboardSetUnicodeString(void *event, uintptr_t length, uint16 *string)'
+  );
+  coreFoundation.CFRelease = coreFoundation.func(
+    'void CFRelease(void *cf)'
+  );
+}
+
+function postKey(keyCode, keyDown, flags) {
+  const event = coreGraphics.CGEventCreateKeyboardEvent(null, keyCode, keyDown);
+  if (!event) throw new Error(`CGEventCreateKeyboardEvent failed for key ${keyCode}`);
+  try {
+    coreGraphics.CGEventSetFlags(event, flags);
+    coreGraphics.CGEventPost(kCGHIDEventTap, event);
+  } finally {
+    coreFoundation.CFRelease(event);
+  }
+}
+
+function sendCommandV() {
+  try {
+    loadFrameworks();
+    postKey(KEY_COMMAND, true, kCGEventFlagMaskCommand);
+    postKey(KEY_V, true, kCGEventFlagMaskCommand);
+    postKey(KEY_V, false, kCGEventFlagMaskCommand);
+    postKey(KEY_COMMAND, false, 0);
+    return { ok: true };
+  } catch (error) {
+    return { ok: false, error: error && error.message };
+  }
+}
+
+// Post a chunk of text as a single keyboard event carrying its Unicode string.
+// The whole chunk is delivered in one event (not char-by-char), so it is fast.
+function postUnicodeChunk(str) {
+  const units = [];
+  for (let i = 0; i < str.length; i++) units.push(str.charCodeAt(i));
+  const buf = Uint16Array.from(units);
+  const down = coreGraphics.CGEventCreateKeyboardEvent(null, 0, true);
+  if (!down) throw new Error('CGEventCreateKeyboardEvent failed');
+  try {
+    coreGraphics.CGEventKeyboardSetUnicodeString(down, buf.length, buf);
+    coreGraphics.CGEventPost(kCGHIDEventTap, down);
+  } finally {
+    coreFoundation.CFRelease(down);
+  }
+  const up = coreGraphics.CGEventCreateKeyboardEvent(null, 0, false);
+  if (!up) return;
+  try {
+    coreGraphics.CGEventKeyboardSetUnicodeString(up, buf.length, buf);
+    coreGraphics.CGEventPost(kCGHIDEventTap, up);
+  } finally {
+    coreFoundation.CFRelease(up);
+  }
+}
+
+// Type text by synthesizing keyboard events carrying the Unicode string —
+// bypassing the clipboard entirely (no backup/restore race, clipboard
+// untouched). Chunked so a huge string doesn't overflow a single event.
+function typeText(text) {
+  const str = String(text == null ? '' : text);
+  if (!str) return { ok: true, chars: 0 };
+  try {
+    loadFrameworks();
+    const CHUNK = 200;
+    for (let i = 0; i < str.length; i += CHUNK) {
+      postUnicodeChunk(str.slice(i, i + CHUNK));
+    }
+    return { ok: true, chars: str.length };
+  } catch (error) {
+    return { ok: false, chars: str.length, error: error && error.message };
+  }
+}
+
+module.exports = { sendCommandV, typeText };

package/lib/mcp-core.js

@@ -0,0 +1,270 @@
+'use strict';
+
+// Pure context-shaping for the MCP server.
+//
+// Given the raw clipboard history + settings (read from the JSON files by the
+// helper, or held in memory by the app), this builds exactly what an AI
+// assistant is allowed to see, applying one filter:
+//
+//   Allowlist by curation - only clips in a group the user shared with AI
+//   ("groups_shared_with_ai", which always includes the auto "AI" group)
+//   expose their content. Everything else is metadata only. Sharing is fully
+//   opt-in per group, so a clip the user put in a shared group is shared as-is.
+//
+// No I/O here: text-blob hydration and image bytes are the caller's job. This
+// keeps the module pure + unit-testable and lets both the helper (file-backed)
+// and the app (memory-backed) reuse the identical boundary.
+
+const model = require('./clipboard-model');
+const search = require('../site/shared/clip-search');
+
+const AI_GROUP_NAME = 'AI';
+const DEFAULT_PREVIEW_CHARS = 280;
+const DEFAULT_LIST_LIMIT = 50;
+
+function sharedGroupSet(settings) {
+  const configured = settings && Array.isArray(settings.groups_shared_with_ai)
+    ? settings.groups_shared_with_ai
+    : [];
+  const set = new Set(configured);
+  // The auto "AI" group is the quick drop-bucket and is always shared.
+  set.add(AI_GROUP_NAME);
+  return set;
+}
+
+// A clip carries a format when the value is inline OR externalized to a blob.
+// Checked without loading the blob: this is availability, not content.
+function hasRichPayload(item, field) {
+  if (!item || item.type === 'image') return false;
+  const names = model.blobFieldNames(field);
+  return !!(item[names.value] || item[names.ref] || item[names.hash]);
+}
+
+function isShared(item, sharedSet) {
+  const groups = model.groupsOf(item);
+  for (const g of groups) if (sharedSet.has(g)) return true;
+  return false;
+}
+
+function previewText(item, chars) {
+  const raw = item && item.type !== 'image'
+    ? String(item.text != null && item.text !== '' ? item.text : (item.textPreview || ''))
+    : '';
+  if (raw.length <= chars) return raw;
+  return `${raw.slice(0, chars)}…`;
+}
+
+function searchableText(item, { sharedSet = null, forceAll = false } = {}) {
+  const shared = sharedSet ? isShared(item, sharedSet) : false;
+  const includeTitle = forceAll || shared;
+  return [
+    includeTitle ? model.titleOf(item) : '',
+    item && item.type === 'image' ? (item.image || '') : (item && item.text != null ? item.text : item && item.textPreview || ''),
+    item && item.type || '',
+    ...(includeTitle ? model.groupsOf(item) : []),
+  ].filter(Boolean).join(' ');
+}
+
+// Shape a single clip for AI consumption. `forcePreview` is set only on the
+// post-approval ('all') path, where the user has explicitly approved reading
+// beyond the allowlist - it surfaces the preview even for a non-shared clip.
+function clipView(item, { sharedSet, previewChars = DEFAULT_PREVIEW_CHARS, forcePreview = false } = {}) {
+  const id = model.itemKey(item);
+  const shared = isShared(item, sharedSet);
+  const base = {
+    id,
+    type: item.type === 'image' ? 'image' : 'text',
+    ts: item.ts || 0,
+    pinned: model.isPinned(item),
+    numpad: model.numpadSlotOf(item),
+    rev: model.clipRevision(item),
+    shared,
+  };
+  if (!shared && !forcePreview) {
+    // Metadata only: no content, no group names, no preview.
+    return base;
+  }
+  if (!shared && forcePreview) base.viaApproval = true;
+  // Only expose the SHARED group names a clip belongs to - never the names of
+  // any private/non-shared groups it is also a member of.
+  base.groups = model.groupsOf(item).filter(g => sharedSet.has(g));
+  if (item.type === 'image') {
+    base.image = item.image || null;
+    if (item.width) base.width = item.width;
+    if (item.height) base.height = item.height;
+    return base;
+  }
+  const title = model.titleOf(item);
+  if (title) base.title = title;
+  base.preview = previewText(item, previewChars);
+  // Advertise that formatting exists WITHOUT shipping it. The raw HTML/RTF is
+  // large and low-value to a model, but knowing a clip is rich is useful.
+  if (hasRichPayload(item, 'html')) base.has_html = true;
+  if (hasRichPayload(item, 'rtf')) base.has_rtf = true;
+  return base;
+}
+
+// The full-text read result shape, shared by the helper's get_clip fast-path and
+// the app's approval-gated read_clip so both stay identical. Group names are
+// filtered to shared-only, matching clipView's policy.
+function fullTextResult(item, sharedSet) {
+  const groups = sharedSet ? model.groupsOf(item).filter(g => sharedSet.has(g)) : model.groupsOf(item);
+  const result = { id: model.itemKey(item), rev: model.clipRevision(item), type: 'text', text: String(item.text || ''), groups, ts: item.ts || 0 };
+  const title = model.titleOf(item);
+  if (title) result.title = title;
+  return result;
+}
+
+// Summary of the user's organisation - the "clipboard / workflows" context.
+function buildContext(history, settings) {
+  const items = Array.isArray(history) ? history : [];
+  const sharedSet = sharedGroupSet(settings);
+  const groupNames = Array.isArray(settings && settings.groups) ? settings.groups : [];
+  const counts = new Map();
+  const numpad = {};
+  let pinnedCount = 0;
+  let sharedCount = 0;
+
+  for (const item of items) {
+    if (model.isPinned(item)) pinnedCount++;
+    const slot = model.numpadSlotOf(item);
+    if (slot != null) numpad[slot] = { id: model.itemKey(item), type: item.type === 'image' ? 'image' : 'text' };
+    for (const g of model.groupsOf(item)) counts.set(g, (counts.get(g) || 0) + 1);
+    if (isShared(item, sharedSet)) sharedCount++;
+  }
+
+  // Only name the SHARED groups. Private/non-shared groups are surfaced as a bare
+  // count so the assistant knows the scale without learning private group names.
+  const groups = groupNames
+    .filter(name => sharedSet.has(name))
+    .map(name => ({ name, shared: true, count: counts.get(name) || 0 }));
+  const privateGroupCount = groupNames.filter(name => !sharedSet.has(name)).length;
+
+  return {
+    totalClips: items.length,
+    sharedClips: sharedCount,
+    pinnedClips: pinnedCount,
+    groups,
+    privateGroupCount,
+    numpadSlots: numpad,
+    aiGroup: AI_GROUP_NAME,
+  };
+}
+
+// List clips. By default returns shared clips with previews (most recent first);
+// pass includeNonShared to also append metadata-only entries for the rest.
+function listClips(history, settings, {
+  limit = DEFAULT_LIST_LIMIT,
+  previewChars = DEFAULT_PREVIEW_CHARS,
+  group = null,
+  includeNonShared = false,
+} = {}) {
+  const items = Array.isArray(history) ? history : [];
+  const sharedSet = sharedGroupSet(settings);
+  const out = [];
+  let nonSharedTotal = 0;
+
+  for (const item of items) {
+    const shared = isShared(item, sharedSet);
+    if (!shared) {
+      nonSharedTotal++;
+      if (!includeNonShared) continue;
+    }
+    if (group && !model.groupsOf(item).includes(group)) continue;
+    out.push(clipView(item, { sharedSet, previewChars }));
+    if (out.length >= limit) break;
+  }
+  return { clips: out, nonSharedTotal, returned: out.length };
+}
+
+// A boundary-aware search doc: the SAME normalized shape the shared engine ranks/filters,
+// but with title/groups HIDDEN unless the clip is shared (or forceAll after approval). So the
+// engine's grammar (title:/since:/is:/…) works while the allowlist boundary is preserved — a
+// `title:` scope on a non-shared clip can never match unless the user approved all-scope.
+function clipToSearchDoc(item, { sharedSet, forceAll = false } = {}) {
+  const visible = forceAll || isShared(item, sharedSet);
+  const isImage = item && item.type === 'image';
+  const body = isImage ? String(item && item.image || '') : String(item && (item.text != null ? item.text : item.textPreview) || '');
+  return {
+    id: model.itemKey(item),
+    type: isImage ? 'image' : 'text',
+    title: visible ? model.titleOf(item) : '',
+    body,
+    groups: visible ? model.groupsOf(item) : [],
+    numpad: model.numpadSlotOf(item),
+    pinned: model.isPinned(item),
+    ts: Number(item && item.ts) || 0,
+    len: isImage ? 0 : body.length,
+    lines: isImage || !body ? 0 : body.split(/\r\n|\r|\n/).length,
+    words: isImage || !body.trim() ? 0 : body.trim().split(/\s+/).length,
+    url: !isImage && /^(?:[a-z][a-z0-9+.-]*:\/\/|www\.)[^\s]+$|^[a-z0-9-]+(?:\.[a-z0-9-]+)+(?:\/[^\s]*)?$/i.test(body.trim()),
+    rich: !isImage && !!(item.html || item.htmlRef || item.htmlHash || item.rtf || item.rtfRef || item.rtfHash),
+  };
+}
+
+// Search. Shared matches return previews; non-shared matches are counted only (the caller
+// decides whether to escalate to an approval-gated full search). Delegates parsing +
+// matching to the SHARED engine (site/shared/clip-search) so the MCP tool understands the
+// SAME language as the app's search field: `title:`, `group:`, `is:pinned`,
+// `since:7d`, `-word`, `/regex/`, `a OR b`, `( )`. Plain words are literal. The old
+// `regex: true` flag still works: the query's free text is read as ONE regex
+// (search.legacyRegexQuery).
+function searchClips(history, settings, {
+  query,
+  regex = false,
+  limit = DEFAULT_LIST_LIMIT,
+  previewChars = DEFAULT_PREVIEW_CHARS,
+  scope = 'shared',
+  now,
+} = {}) {
+  const items = Array.isArray(history) ? history : [];
+  const sharedSet = sharedGroupSet(settings);
+  const parsed = search.parseQuery(regex ? search.legacyRegexQuery(query) : query);
+  const matches = [];
+  let nonSharedMatches = 0;
+
+  for (const item of items) {
+    const shared = isShared(item, sharedSet);
+    const doc = clipToSearchDoc(item, { sharedSet, forceAll: scope === 'all' });
+    if (!search.matchDoc(doc, parsed, { now })) continue;
+    if (shared) {
+      if (matches.length < limit) matches.push(clipView(item, { sharedSet, previewChars }));
+    } else {
+      nonSharedMatches++;
+      // scope === 'all' is only used by the app AFTER approval; it shapes the
+      // non-shared match as a real preview so the assistant can read it.
+      if (scope === 'all' && matches.length < limit) {
+        matches.push(clipView(item, { sharedSet, previewChars, forcePreview: true }));
+      }
+    }
+  }
+  return { matches, nonSharedMatches, returned: matches.length };
+}
+
+// Resolve a single clip id for a full-text read. Returns the decision; the
+// caller hydrates the text only when allowed. `reason` is one of:
+// 'ok' | 'not_found' | 'not_shared'.
+function resolveForRead(history, settings, id) {
+  const items = Array.isArray(history) ? history : [];
+  const sharedSet = sharedGroupSet(settings);
+  const item = items.find(i => model.itemKey(i) === id);
+  if (!item) return { reason: 'not_found', item: null, shared: false };
+  const shared = isShared(item, sharedSet);
+  if (!shared) return { reason: 'not_shared', item, shared: false };
+  return { reason: 'ok', item, shared: true };
+}
+
+module.exports = {
+  AI_GROUP_NAME,
+  DEFAULT_PREVIEW_CHARS,
+  DEFAULT_LIST_LIMIT,
+  sharedGroupSet,
+  isShared,
+  previewText,
+  clipView,
+  fullTextResult,
+  buildContext,
+  listClips,
+  searchClips,
+  resolveForRead,
+};