Skip to content

Edge-Drop is a clipboard shelf on the edge of your screen. Hover to open it. Drag files and images into any app, click to copy text and links. Free and open-source for Windows.

36.8 KB
Raw Blame
/**
 * In-memory + on-disk store for clipboard history.
 *
 * Responsibilities:
 *   - Keep an ordered list (most recent first) of ClipboardItem.
 *   - Deduplicate by content signature so re-copies bump `hitCount` instead of
 *     adding a clone.
 *   - Enforce a size cap, evicting the oldest items that aren't kept
 *     (pinned or noted, see isKept).
 *   - Persist the index to JSON and image bytes to per-item PNG files.
 *   - Convert internal items to the serializable DTO form for the renderer.
 */
import { existsSync, readFileSync, writeFileSync, rmSync, statSync, readdirSync, openSync, writeSync, fsyncSync, closeSync, renameSync } from 'node:fs'
import { join, extname, basename as pathBasename } from 'node:path'
import { nativeImage, safeStorage } from 'electron'
import { thumbnailUrlForFile, thumbnailUrlForStoredImage } from '../main/imageProtocol'
import {
  type ClipboardItem,
  type ClipboardItemDto,
  type DragRequest,
  type ItemData,
  type MergeResult,
  type FileEntry,
  MAX_STACK
} from '../../shared/types'
import { PATHS } from './paths'
import { createId } from './ids'
import { contentSignature } from './signature'
import { MAX_ITEM_HTML_CHARS } from '../clipboard/formats'
import { isKept, joinNotes, normalizeNote, noteFromLegacy, type ItemMetaPatch } from '../../shared/itemMeta'
import { linkTitleFromHtml } from '../../shared/linkText'

/** Write an already-normalized note, removing the field when empty. */
function applyNote(it: ClipboardItem, note: string | undefined): void {
  if (note) it.note = note
  else delete it.note
}

/**
 * Replace a file only once its new contents are on disk: written to a side file, flushed, then
 * swapped in. A crash or power cut mid-save leaves the previous file, never a cut-off or empty one.
 */
function writeFileAtomic(file: string, data: string): void {
  const tmp = `${file}.tmp`
  const fd = openSync(tmp, 'w')
  try {
    writeSync(fd, data, null, 'utf8')
    fsyncSync(fd)
  } finally {
    closeSync(fd)
  }
  renameSync(tmp, file)
}

/** Read a file, retrying briefly while another process (antivirus, backup) holds it. */
function readFileRetrying(file: string): Buffer {
  for (let attempt = 0; ; attempt++) {
    try {
      return readFileSync(file)
    } catch (err) {
      const code = (err as NodeJS.ErrnoException).code
      if (attempt >= 2 || (code !== 'EBUSY' && code !== 'EPERM' && code !== 'EACCES')) throw err
      Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 100)
    }
  }
}

/** Maps a signature -> item id so dedup is O(1). */
interface Index {
  items: ClipboardItem[]
}

/**
 * A saved history file's items: the encrypted (DPAPI) envelope, or the plain JSON of early versions.
 * `index` is null when the file cannot be read (it will not decrypt, or it is damaged).
 */
function readIndex(raw: Buffer): { index: Index | null; encrypted: boolean; plain: boolean } {
  let parsedJson: any = null
  try {
    parsedJson = JSON.parse(raw.toString('utf8').trim())
  } catch {
    /* Raw non-JSON payload */
  }
  const valid = (index: any): Index | null =>
    index && Array.isArray(index.items) ? { items: index.items.filter((it: any) => it && it.data && typeof it.id === 'string') } : null

  if (parsedJson && parsedJson.encrypted === true && typeof parsedJson.payload === 'string') {
    // Encrypted DPAPI Envelope
    let index: Index | null = null
    if (safeStorage.isEncryptionAvailable()) {
      try {
        index = valid(JSON.parse(safeStorage.decryptString(Buffer.from(parsedJson.payload, 'base64'))))
      } catch (err) {
        console.error('[ItemStore] DPAPI decryption failed:', err)
      }
    } else {
      console.warn('[ItemStore] safeStorage unavailable to decrypt items.json')
    }
    return { index, encrypted: true, plain: false }
  }
  // Plain JSON (Legacy v0.1.1 format from active users)
  if (parsedJson && Array.isArray(parsedJson.items)) return { index: valid(parsedJson), encrypted: false, plain: true }
  return { index: null, encrypted: false, plain: false }
}

/**
 * Invoked with every batch of items permanently removed from history, no
 * matter which door removed them (manual delete, batch delete, clear,
 * auto-delete prune, or silent capacity eviction). The staged-temp lifecycle
 * manager uses it to reap orphaned artifacts.
 */
export type ItemsRemovedListener = (removed: readonly ClipboardItem[]) => void

export class ItemStore {
  private items: ClipboardItem[] = []
  private sigToId = new Map<string, string>()
  /** Small, bounded thumbnails for renderer DTOs. Original image bytes stay on disk. */
  private previewCache = new Map<string, string>()
  /**
   * The saved history could not be read this session and could not be set aside either (the file was
   * held by another process, or the copy failed). It is never written over: nothing is saved until a
   * later launch reads it, so a passing failure costs this session's new copies, never the history.
   */
  private indexUnreadable = false
  /** The saved history is encrypted: it is never replaced by a plain copy. */
  private indexEncrypted = false

  constructor(private readonly onRemoved?: ItemsRemovedListener) {}

  private notifyRemoved(removed: ClipboardItem[]): void {
    if (removed.length === 0) return
    try {
      this.onRemoved?.(removed)
    } catch (err) {
      console.error('[ItemStore] onRemoved listener failed:', err)
    }
  }

  /** Load persisted state from disk. Called once at startup. */
  load(): void {
    this.indexUnreadable = false
    this.indexEncrypted = false
    this.items = []
    const file = PATHS.indexFile()
    try {
      if (existsSync(file)) this.loadIndex(file)
    } catch (err) {
      console.error('[ItemStore] Failed to load index file:', err)
      // it could not even be read (held by another process, no access): leave it alone this session
      this.items = []
      this.indexUnreadable = existsSync(file)
    }
    this.rebuildIndex()
    // a history set aside by an earlier launch comes back as soon as it can be read
    if (!this.indexUnreadable) this.mergeSetAside(file)
  }

  private loadIndex(file: string): void {
    const rawBuffer = readFileRetrying(file)
    // nothing in it to keep (older builds wrote in place, and a crash mid-save could leave this)
    if (!rawBuffer.toString('utf8').trim()) return
    const read = readIndex(rawBuffer)
    if (read.encrypted) this.indexEncrypted = true
    if (!read.index) {
      this.setAsideUnreadable(file, rawBuffer)
      return
    }
    this.items = read.index.items
    const upgraded = this.upgradeItems(this.items)

    // Auto-migrate legacy plain JSON: create backup & upgrade to DPAPI encryption
    if (read.plain || upgraded) {
      console.log('[ItemStore] Migrating items.json to DPAPI safeStorage encryption and disk payloads...')
      try {
        const backupFile = `${file}.v1.bak`
        if (!existsSync(backupFile)) {
          writeFileSync(backupFile, rawBuffer)
        }
        this.persist()
      } catch (err) {
        console.error('[ItemStore] Auto-migration backup/persist failed:', err)
      }
    }
  }

  /**
   * Bring items saved by older versions up to date. Returns true when anything changed, so the
   * history is saved again in the current shape.
   */
  private upgradeItems(items: ClipboardItem[]): boolean {
    // Auto-migrate large text items to disk payload files
    let changed = false
    for (const it of items) {
      // A hand-edited or damaged file must never feed an odd note to the
      // renderer: re-run the same cleanup as writes. Items saved with the
      // old label + tags get them as one note (they were pinned when
      // named, and stay pinned).
      const legacy = it as ClipboardItem & { label?: unknown; tags?: unknown }
      if ('label' in legacy || 'tags' in legacy) {
        applyNote(it, joinNotes(normalizeNote(it.note), noteFromLegacy(legacy.label, legacy.tags)))
        delete legacy.label
        delete legacy.tags
        changed = true
      } else if ('note' in it) {
        applyNote(it, normalizeNote(it.note))
      }
      if (it.data.kind === 'text') {
        // links saved before page titles were kept: read it from the saved html once
        if (it.data.isUrl && it.data.html && !it.data.linkTitle) {
          const linkTitle = linkTitleFromHtml(it.data.html, it.data.text.trim())
          if (linkTitle) it.data.linkTitle = linkTitle
        }
        if (!it.data.hasFullPayload && it.data.text.length > 300) {
          this.writeTextPayload(it.id, it.data.text)
          it.data.hasFullPayload = true
          it.data.previewText = it.data.text.slice(0, 300)
          it.data.text = it.data.previewText
          changed = true
        }
        if (it.data.html && it.data.html.length > MAX_ITEM_HTML_CHARS) {
          delete it.data.html
          changed = true
        }
      }
    }
    return changed
  }

  /**
   * The saved history is there but this launch cannot read it (it will not decrypt, or it is damaged).
   * A byte-for-byte copy is set aside first and checked; a later launch that can read it merges it
   * back (mergeSetAside). Only once that copy is safe does this session start a new history. If the
   * copy cannot be made, nothing is saved this session and items.json stays exactly as it is.
   */
  private setAsideUnreadable(file: string, raw: Buffer): void {
    console.warn('[ItemStore] Saved history could not be read; setting it aside to merge back later')
    const copy = `${file}.unreadable-${Date.now()}.bak`
    try {
      writeFileSync(copy, raw)
      if (!readFileSync(copy).equals(raw)) throw new Error('the copy does not match')
    } catch (err) {
      console.error('[ItemStore] Could not set the saved history aside; not saving this session:', err)
      this.indexUnreadable = true
    }
  }

  /**
   * Merge back histories set aside because a launch could not read them, and the .corrupted copies
   * older builds made in the same situation: once one reads, its items that are not here already
   * join the history (newest first). The copy is removed only after the merged history is saved.
   */
  private mergeSetAside(file: string): void {
    const dir = PATHS.root()
    const base = pathBasename(file)
    let names: string[] = []
    try {
      names = readdirSync(dir)
        .filter((n) => (n.startsWith(`${base}.unreadable-`) && n.endsWith('.bak')) || n.startsWith(`${base}.corrupted.`))
        .sort()
    } catch {
      return
    }
    for (const name of names) {
      const copy = join(dir, name)
      let read: ReturnType<typeof readIndex>
      try {
        read = readIndex(readFileSync(copy))
      } catch {
        continue
      }
      if (!read.index) continue // still unreadable: kept for a later launch
      const here = new Set(this.items.map((it) => it.id))
      const back = read.index.items.filter((it) => !here.has(it.id))
      this.upgradeItems(back)
      const fresh = back.filter((it) => !this.sigToId.has(this.signatureOf(it)))
      if (fresh.length) {
        this.items = [...this.items, ...fresh].sort((x, y) => y.capturedAt - x.capturedAt)
        this.rebuildIndex()
      }
      if (!this.persistSync()) break // not saved: keep every copy and try again next launch
      rmSync(copy, { force: true })
      console.log(`[ItemStore] Merged ${fresh.length} items back from ${name}`)
    }
  }

  /** The signature an item is deduplicated by (long texts by their full text). */
  private signatureOf(it: ClipboardItem): string {
    return it.data.kind === 'text' && it.data.hasFullPayload
      ? contentSignature({ ...it.data, text: this.getFullText(it.id) })
      : contentSignature(it.data)
  }

  private rebuildIndex(): void {
    this.sigToId.clear()
    for (const it of this.items) this.sigToId.set(this.signatureOf(it), it.id)
  }

  private persistTimer: ReturnType<typeof setTimeout> | null = null

  /** Persist the current index to disk. Debounced to prevent main thread blocking during UI transitions. */
  private persist(): void {
    if (this.persistTimer) {
      clearTimeout(this.persistTimer)
    }
    this.persistTimer = setTimeout(() => {
      this.persistTimer = null
      this.persistSync()
    }, 150)
  }

  /** Synchronous disk write (called by debounced timer or on app shutdown). True when written. */
  public persistSync(): boolean {
    if (this.persistTimer) {
      clearTimeout(this.persistTimer)
      this.persistTimer = null
    }
    // the saved history could not be read or set aside this session: it is never written over (see load)
    if (this.indexUnreadable) return false
    try {
      const indexObj: Index = { items: this.items }
      const jsonStr = JSON.stringify(indexObj)
      const file = PATHS.indexFile()

      if (safeStorage.isEncryptionAvailable()) {
        const encryptedBuf = safeStorage.encryptString(jsonStr)
        const envelope = {
          v: 2,
          encrypted: true,
          payload: encryptedBuf.toString('base64')
        }
        writeFileAtomic(file, JSON.stringify(envelope))
        this.indexEncrypted = true
        return true
      } else if (this.indexEncrypted) {
        // never trade encrypted history for a plain copy; the next save with encryption back writes it
        console.warn('[ItemStore] Encryption unavailable; not replacing the encrypted history with a plain copy')
        return false
      }
      writeFileAtomic(file, JSON.stringify(indexObj))
      return true
    } catch (err) {
      console.error('[ItemStore] Persistence failed:', err)
      return false
    }
  }

  /**
   * Enforce the size cap by evicting the oldest items that aren't kept. Walks
   * from the tail (oldest) forward, skipping pinned and noted items.
   */
  private trim(limit: number): void {
    if (this.items.length <= limit) return
    const need = this.items.length - limit
    const survivors: ClipboardItem[] = []
    const evicted: ClipboardItem[] = []
    let stillNeed = need
    for (let i = this.items.length - 1; i >= 0; i--) {
      const it = this.items[i]
      if (stillNeed > 0 && !isKept(it)) {
        this.sigToId.delete(contentSignature(it.data))
        if (it.data.kind === 'image') this.removeImageFile(it.data.imageId)
        if (it.data.kind === 'image-collection') {
          it.data.images.forEach((img) => this.removeImageFile(img.imageId))
        }
        if (it.data.kind === 'text') this.removeTextPayload(it.id)
        evicted.push(it)
        stillNeed--
      } else {
        survivors.unshift(it)
      }
    }
    this.items = survivors
    this.notifyRemoved(evicted)
  }

  /**
   * Add or refresh a piece of content.
   * Returns true if the list actually changed (so callers can decide to push).
   */
  add(data: ItemData, limit: number): boolean {
    if (data.kind === 'text' && data.text.length > 500000) {
      data = { ...data, text: data.text.slice(0, 500000) }
    }
    const sig = contentSignature(data)
    const existingId = this.sigToId.get(sig)
    const now = Date.now()

    // A link copied with its page title (browsers put `<a href>Title</a>` in
    // the html): keep the title for the card and search.
    if (data.kind === 'text' && data.isUrl && data.html && !data.linkTitle) {
      const linkTitle = linkTitleFromHtml(data.html, data.text.trim())
      if (linkTitle) data = { ...data, linkTitle }
    }

    if (existingId) {
      const idx = this.items.findIndex((it) => it.id === existingId)
      if (idx >= 0) {
        const it = this.items[idx]
        // Bump count and move to front (and learn the page title if this copy brought one).
        const updated: ClipboardItem = { ...it, hitCount: it.hitCount + 1, capturedAt: now }
        if (data.kind === 'text' && data.linkTitle && updated.data.kind === 'text' && !updated.data.linkTitle) {
          updated.data = { ...updated.data, linkTitle: data.linkTitle }
        }
        this.items.splice(idx, 1)
        this.items.unshift(updated)
        this.persist()
        return true
      }
    }

    const id = createId()
    let finalData = data
    if (data.kind === 'text') {
      if (data.html && data.html.length > MAX_ITEM_HTML_CHARS) {
        delete data.html
      }
      if (data.text.length > 300) {
        this.writeTextPayload(id, data.text)
        finalData = {
          ...data,
          hasFullPayload: true,
          previewText: data.text.slice(0, 300),
          text: data.text.slice(0, 300)
        }
      }
    }

    const item: ClipboardItem = { id, data: finalData, capturedAt: now, hitCount: 1, pinned: false }
    this.items.unshift(item)
    this.sigToId.set(sig, id)
    if (data.kind === 'image') this.writeImageFile(data.imageId)
    this.trim(limit)
    this.persist()
    return true
  }

  /**
   * Touch an item (e.g. on paste) to update its timestamp and hitCount,
   * moving unpinned items to the front of the Recent list.
   */
  touch(id: string): boolean {
    const idx = this.items.findIndex((it) => it.id === id)
    if (idx < 0) return false
    const it = this.items[idx]
    const now = Date.now()
    const updated: ClipboardItem = { ...it, hitCount: it.hitCount + 1, capturedAt: now }

    if (!it.pinned) {
      this.items.splice(idx, 1)
      this.items.unshift(updated)
    } else {
      this.items[idx] = updated
    }

    this.persist()
    return true
  }

  setPinned(id: string, pinned: boolean): void {
    const it = this.items.find((x) => x.id === id)
    if (!it) return
    it.pinned = pinned
    this.persist()
  }

  /**
   * Set or clear an item's note. Normalized here, so nothing unclean is ever
   * stored. The pin is left alone: a note keeps the item by itself (history
   * limit, auto-delete and "clear" skip noted items, see isKept). Returns
   * false when the item is gone.
   */
  setMeta(id: string, patch: ItemMetaPatch): boolean {
    const it = this.items.find((x) => x.id === id)
    if (!it || !patch || typeof patch !== 'object') return false
    if ('note' in patch) applyNote(it, normalizeNote(patch.note))
    this.persist()
    return true
  }

  delete(id: string): void {
    const idx = this.items.findIndex((x) => x.id === id)
    if (idx < 0) return
    const [removed] = this.items.splice(idx, 1)
    this.sigToId.delete(contentSignature(removed.data))
    if (removed.data.kind === 'image') this.removeImageFile(removed.data.imageId)
    if (removed.data.kind === 'image-collection') {
      removed.data.images.forEach((img) => this.removeImageFile(img.imageId))
    }
    if (removed.data.kind === 'text') this.removeTextPayload(removed.id)
    this.persistSync()
    this.notifyRemoved([removed])
  }

  deleteBatch(ids: string[]): void {
    if (!ids || ids.length === 0) return
    const set = new Set(ids)
    const toRemove: ClipboardItem[] = []
    this.items = this.items.filter((it) => {
      if (set.has(it.id)) {
        toRemove.push(it)
        return false
      }
      return true
    })

    for (const removed of toRemove) {
      this.sigToId.delete(contentSignature(removed.data))
      if (removed.data.kind === 'image') this.removeImageFile(removed.data.imageId)
      if (removed.data.kind === 'image-collection') {
        removed.data.images.forEach((img) => this.removeImageFile(img.imageId))
      }
      if (removed.data.kind === 'text') this.removeTextPayload(removed.id)
    }
    this.persistSync()
    this.notifyRemoved(toRemove)
  }

  merge(sourceId: string, targetId: string): MergeResult {
    if (sourceId === targetId) return { ok: false }
    const srcIdx = this.items.findIndex(x => x.id === sourceId)
    const tgtIdx = this.items.findIndex(x => x.id === targetId)
    if (srcIdx < 0 || tgtIdx < 0) return { ok: false, reason: 'notfound' }

    const src = this.items[srcIdx]
    const tgt = this.items[tgtIdx]

    // Text and links cannot be merged into stacks.
    // NOTE: message is a translation key resolved renderer-side (see toast.*
    // in translations.ts), never display English from the store.
    if (src.data.kind === 'text' || tgt.data.kind === 'text') {
      return { ok: false, reason: 'incompatible', message: 'toast.mergeTextLinks' }
    }

    let newData: ItemData | null = null

    const getItemPaths = (item: ClipboardItem): string[] => {
      if (item.data.kind === 'files') return item.data.paths
      if (item.data.kind === 'image') return [this.imagePath(item.data.imageId, item.data.ext)]
      if (item.data.kind === 'image-collection') return item.data.images.map((img) => this.imagePath(img.imageId, img.ext))
      return []
    }

    const isPureImage = (item: ClipboardItem): boolean => {
      return item.data.kind === 'image' || item.data.kind === 'image-collection'
    }

    if (isPureImage(src) && isPureImage(tgt)) {
      // Pure Image(s) + Pure Image(s) -> Image Collection
      const srcData = src.data
      const tgtData = tgt.data
      const srcImages = srcData.kind === 'image-collection'
        ? srcData.images
        : srcData.kind === 'image'
          ? [{ imageId: srcData.imageId, width: srcData.width, height: srcData.height, bytes: srcData.bytes, ext: srcData.ext, source: srcData.source, fileName: srcData.fileName }]
          : []
      const tgtImages = tgtData.kind === 'image-collection'
        ? tgtData.images
        : tgtData.kind === 'image'
          ? [{ imageId: tgtData.imageId, width: tgtData.width, height: tgtData.height, bytes: tgtData.bytes, ext: tgtData.ext, source: tgtData.source, fileName: tgtData.fileName }]
          : []
      const seen = new Set(tgtImages.map((i) => i.imageId))
      const combined = [...tgtImages, ...srcImages.filter((i) => !seen.has(i.imageId))]

      if (combined.length > MAX_STACK) return { ok: false, reason: 'full', message: 'toast.mergeImagesFull' }
      newData = { kind: 'image-collection', images: combined }
    } else if (
      (src.data.kind === 'files' || src.data.kind === 'image' || src.data.kind === 'image-collection') &&
      (tgt.data.kind === 'files' || tgt.data.kind === 'image' || tgt.data.kind === 'image-collection')
    ) {
      // Mixed combinations: Files + Files, Image(s) + Files, Files + Image(s)
      const srcPaths = getItemPaths(src)
      const tgtPaths = getItemPaths(tgt)
      const seen = new Set(tgtPaths)
      const combined = [...tgtPaths, ...srcPaths.filter((p) => !seen.has(p))]

      if (combined.length > MAX_STACK) return { ok: false, reason: 'full', message: 'toast.mergeFilesFull' }
      newData = { kind: 'files', paths: combined }
    }

    if (!newData) {
      return { ok: false, reason: 'incompatible', message: 'toast.mergeIncompatible' }
    }

    // Update target item
    this.sigToId.delete(contentSignature(tgt.data))
    tgt.data = newData
    this.sigToId.set(contentSignature(newData), tgt.id)
    tgt.capturedAt = Date.now() // bump time

    // The source card disappears, so carry what the user gave it: the
    // target gets both notes (and with them, is kept).
    if (src.note) applyNote(tgt, joinNotes(tgt.note, src.note))

    // Remove source item completely but DO NOT delete its underlying files/images
    // because they are now owned by the target!
    const [removed] = this.items.splice(srcIdx, 1)
    this.sigToId.delete(contentSignature(removed.data))

    this.persist()
    return { ok: true }
  }

  public removeSubitem(req: DragRequest): boolean {
    const sourceItem = this.get(req.id)
    if (!sourceItem) return false
    const sourceIndex = this.items.findIndex(i => i.id === req.id)
    if (sourceIndex === -1) return false

    if (sourceItem.data.kind === 'image-collection' && req.imageId) {
      const imgIdx = sourceItem.data.images.findIndex(i => i.imageId === req.imageId)
      if (imgIdx === -1) return false
      
      sourceItem.data.images.splice(imgIdx, 1)
      
      if (sourceItem.data.images.length === 1) {
        sourceItem.data = { kind: 'image', ...sourceItem.data.images[0] }
      } else if (sourceItem.data.images.length === 0) {
        this.items.splice(sourceIndex, 1)
      }
      this.rebuildIndex()
      this.persist()
      return true
    }

    if (req.paths && req.paths.length > 0 && sourceItem.data.kind === 'files') {
      const targetPaths = req.paths
      sourceItem.data.paths = sourceItem.data.paths.filter(p => !targetPaths.includes(p))
      
      if (sourceItem.data.paths.length === 0) {
        this.items.splice(sourceIndex, 1)
      }
      this.rebuildIndex()
      this.persist()
      return true
    }

    return false
  }

  public split(req: DragRequest): boolean {
    const sourceItem = this.get(req.id)
    if (!sourceItem) return false
    const sourceIndex = this.items.findIndex(i => i.id === req.id)
    if (sourceIndex === -1) return false

    // Splitting from an image collection
    if (sourceItem.data.kind === 'image-collection' && req.imageId) {
      const imgIdx = sourceItem.data.images.findIndex(i => i.imageId === req.imageId)
      if (imgIdx === -1) return false
      
      const targetImg = sourceItem.data.images[imgIdx]
      sourceItem.data.images.splice(imgIdx, 1)
      
      if (sourceItem.data.images.length === 1) {
        sourceItem.data = { kind: 'image', ...sourceItem.data.images[0] }
      } else if (sourceItem.data.images.length === 0) {
        this.items.splice(sourceIndex, 1)
      }

      const newItem: ClipboardItem = {
        id: createId(),
        capturedAt: Date.now(),
        hitCount: 1,
        pinned: false,
        data: { kind: 'image', ...targetImg }
      }
      this.items.splice(req.splitPlacement === 'after' ? sourceIndex + 1 : sourceIndex, 0, newItem)
      this.rebuildIndex()
      this.persist()
      return true
    }

    // Splitting from a file collection
    if (req.paths && req.paths.length > 0 && sourceItem.data.kind === 'files') {
      const sourcePaths = sourceItem.data.paths
      const targetPaths = req.paths
      
      sourceItem.data.paths = sourcePaths.filter(p => !targetPaths.includes(p))
      
      if (sourceItem.data.paths.length === 0) {
        this.items.splice(sourceIndex, 1)
      }

      let newData: ItemData = { kind: 'files', paths: targetPaths }
      if (targetPaths.length === 1) {
        const p = targetPaths[0]
        const pLower = p.toLowerCase()
        const isFromManagedDir = pLower.includes('images') || pLower.includes('temp') || pLower.includes('edge-drop')
        if (isImageExt(p) && isFromManagedDir) {
          const imgName = pathBasename(p)
          let imageId = imgName.split('.')[0]
          const ext = (extname(p).slice(1) || 'png').toLowerCase()
          if (!/^[a-z0-9]{6,12}-[a-z0-9]{6,12}$/i.test(imageId)) {
            imageId = createId()
            try {
              if (existsSync(p)) {
                const rawBytes = readFileSync(p)
                this.stageImageBytes(imageId, rawBytes, ext)
              }
            } catch {}
          }
          let bytes = 0
          let width = 0
          let height = 0
          try {
            bytes = statSync(p).size
            const img = nativeImage.createFromPath(p)
            if (!img.isEmpty()) {
              const sz = img.getSize()
              width = sz.width
              height = sz.height
            }
          } catch {}
          newData = { kind: 'image', imageId, width, height, bytes, ext }
        }
      }

      const newItem: ClipboardItem = {
        id: createId(),
        capturedAt: Date.now(),
        hitCount: 1,
        pinned: false,
        data: newData
      }
      this.items.splice(req.splitPlacement === 'after' ? sourceIndex + 1 : sourceIndex, 0, newItem)
      this.rebuildIndex()
      this.persist()
      return true
    }

    return false
  }

  /** Remove everything that isn't kept (pinned or noted). */
  clearUnpinned(): void {
    const kept: ClipboardItem[] = []
    const removed: ClipboardItem[] = []
    for (const it of this.items) {
      if (isKept(it)) kept.push(it)
      else {
        this.sigToId.delete(contentSignature(it.data))
        if (it.data.kind === 'image') this.removeImageFile(it.data.imageId)
        if (it.data.kind === 'image-collection') {
          it.data.images.forEach((img) => this.removeImageFile(img.imageId))
        }
        if (it.data.kind === 'text') this.removeTextPayload(it.id)
        removed.push(it)
      }
    }
    this.items = kept
    this.persistSync()
    this.notifyRemoved(removed)
  }

  pruneExpired(hours: number): boolean {
    if (!hours || hours <= 0) return false
    const cutoff = Date.now() - hours * 3600 * 1000
    const kept: ClipboardItem[] = []
    const expired: ClipboardItem[] = []
    for (const it of this.items) {
      if (isKept(it) || it.capturedAt >= cutoff) {
        kept.push(it)
      } else {
        expired.push(it)
        this.sigToId.delete(contentSignature(it.data))
        if (it.data.kind === 'image') this.removeImageFile(it.data.imageId)
        if (it.data.kind === 'image-collection') {
          it.data.images.forEach((img) => this.removeImageFile(img.imageId))
        }
      }
    }
    if (expired.length > 0) {
      this.items = kept
      this.persistSync()
      this.notifyRemoved(expired)
    }
    return expired.length > 0
  }

  get(id: string): ClipboardItem | undefined {
    return this.items.find((x) => x.id === id)
  }

  list(): readonly ClipboardItem[] {
    return this.items
  }

  /* ----------------------------- image files ----------------------------- */

  /**
   * Build a display-sized image preview. Sending originals as base64 data URLs
   * duplicates every image in the main process, IPC payload and renderer heap.
   */
  imageToDataUrl(imageId: string, ext?: string): string | null {
    const THUMB_SIZE = 240
    const PREVIEW_CACHE_MAX = 20
    const cacheKey = `${imageId}.${ext || ''}`
    const cached = this.previewCache.get(cacheKey)
    if (cached) {
      this.previewCache.delete(cacheKey)
      this.previewCache.set(cacheKey, cached)
      return cached
    }
    try {
      let img: any = nativeImage.createFromPath(this.imagePath(imageId, ext))
      if (img.isEmpty()) return null
      const size = img.getSize()
      let thumb: any = size.width > THUMB_SIZE || size.height > THUMB_SIZE
        ? img.resize({ width: THUMB_SIZE, quality: 'good' })
        : img
      const url = thumb.toDataURL({ scaleFactor: 1 })
      img = null
      thumb = null
      if (this.previewCache.size >= PREVIEW_CACHE_MAX) {
        this.previewCache.delete(this.previewCache.keys().next().value!)
      }
      this.previewCache.set(cacheKey, url)
      return url
    } catch {
      return null
    }
  }

  /**
   * Stage an image's bytes from a clipboard capture. The image was already
   * written to userData/images by the clipboard watcher (which has the raw
   * nativeImage); here we just no-op because the file already exists.
   * Kept for symmetry / future use.
   */
  private writeImageFile(_imageId: string): void {
    /* no-op: bytes already on disk from capture */
  }

  public getImagePath(imageId: string, ext?: string): string {
    return this.imagePath(imageId, ext)
  }

  private imagePath(imageId: string, ext?: string): string {
    if (ext) {
      const cleanExt = ext.startsWith('.') ? ext.slice(1) : ext
      return join(PATHS.imagesDir(), `${imageId}.${cleanExt}`)
    }
    const dir = PATHS.imagesDir()
    if (existsSync(dir)) {
      try {
        const files = readdirSync(dir)
        for (const f of files) {
          if (f.startsWith(`${imageId}.`)) {
            return join(dir, f)
          }
        }
      } catch { /* ignore */ }
    }
    return join(PATHS.imagesDir(), `${imageId}.png`)
  }

  /**
   * Resolve the on-disk path for a stored image, recovering via a directory
   * scan when the exact extension path is missing (e.g. the capture was
   * re-staged with a different ext). Returns null only when the image is
   * genuinely unrecoverable — callers must surface that to the user instead
   * of silently degrading to low-res previews.
   */
  public resolveStoredImagePath(imageId: string, ext?: string): string | null {
    if (!imageId) return null
    if (ext) {
      const cleanExt = ext.startsWith('.') ? ext.slice(1) : ext
      const primary = join(PATHS.imagesDir(), `${imageId}.${cleanExt}`)
      if (existsSync(primary)) return primary
    }
    // Recovery: scan the images dir for any extension matching this id.
    try {
      const scanned = this.imagePath(imageId, undefined)
      if (existsSync(scanned)) return scanned
    } catch { /* ignore */ }
    return null
  }

  /**
   * True when at least one image of a collection is still recoverable on
   * disk. Used as a fast pre-check so paste can abort with an explicit error
   * before mutating any UI state.
   */
  public hasRecoverableCollectionImage(images: Array<{ imageId: string; ext?: string }>): boolean {
    return images.some((img) => this.resolveStoredImagePath(img.imageId, img.ext) !== null)
  }

  private removeImageFile(imageId: string): void {
    for (const key of this.previewCache.keys()) {
      if (key.startsWith(imageId)) this.previewCache.delete(key)
    }
    const dir = PATHS.imagesDir()
    if (!existsSync(dir)) return
    try {
      const files = readdirSync(dir)
      for (const f of files) {
        if (f.startsWith(`${imageId}.`)) {
          rmSync(join(dir, f), { force: true })
        }
      }
    } catch {
      /* ignore */
    }
  }

  private textPayloadPath(id: string): string {
    return join(PATHS.payloadsDir(), `${id}.txt`)
  }

  private writeTextPayload(id: string, text: string): void {
    try {
      writeFileSync(this.textPayloadPath(id), text, 'utf8')
    } catch { /* ignore */ }
  }

  private removeTextPayload(id: string): void {
    try {
      const p = this.textPayloadPath(id)
      if (existsSync(p)) rmSync(p, { force: true })
    } catch { /* ignore */ }
  }

  public getFullText(id: string): string {
    const item = this.items.find((x) => x.id === id)
    if (!item || item.data.kind !== 'text') return ''
    if (item.data.hasFullPayload) {
      try {
        const p = this.textPayloadPath(id)
        if (existsSync(p)) {
          return readFileSync(p, 'utf8')
        }
      } catch { /* ignore */ }
    }
    return item.data.text
  }

  /* ------------------------------- DTO ----------------------------------- */

  /** Snapshot the whole list as renderer-safe DTOs (images inlined). */
  toDto(): ClipboardItemDto[] {
    return this.items.map((it) => {
      if (it.data.kind === 'image') {
        const { kind, imageId, width, height, bytes, ext, source, fileName } = it.data
        return {
          ...it,
          data: { kind, imageId, width, height, bytes, ext, source, fileName, preview: thumbnailUrlForStoredImage(imageId) }
        }
      }
      if (it.data.kind === 'image-collection') {
        const imagesWithPreviews = it.data.images.map((img) => ({
          ...img,
          preview: thumbnailUrlForStoredImage(img.imageId)
        }))
        return {
          ...it,
          data: { kind: 'image-collection', images: imagesWithPreviews }
        }
      }
      if (it.data.kind === 'files') {
        // Build per-file metadata entries. Generate image preview protocol URLs for image files.
        let imagePreviewCount = 0
        const entries = it.data.paths.map((p) => {
          const entry = buildFileEntry(p)
          if (entry.isImage && imagePreviewCount < 20) {
            imagePreviewCount++
            return {
              ...entry,
              preview: thumbnailUrlForFile(p)
            }
          }
          return entry
        })
        return {
          ...it,
          data: { ...it.data, entries }
        }
      }
      if (it.data.kind === 'text') {
        const d = it.data
        return {
          ...it,
          data: {
            kind: 'text',
            text: d.text,
            isUrl: d.isUrl,
            isColor: d.isColor,
            hasFullPayload: d.hasFullPayload,
            previewText: d.previewText,
            linkTitle: d.linkTitle,
            // html itself stays in main (can be large); the renderer only
            // needs to know it exists to offer "Paste as plain text".
            hasHtml: !!d.html
          }
        }
      }
      return { ...it, data: it.data }
    })
  }

  /** Persist a brand-new image captured from the clipboard to its PNG file. */
  stageImageBytes(imageId: string, png: Buffer, ext = 'png'): void {
    try {
      writeFileSync(this.imagePath(imageId, ext), png)
    } catch {
      /* ignore */
    }
  }
}

/** Check if a file path points to an image by extension. */
function isImageExt(p: string): boolean {
  return /\.(png|jpe?g|gif|webp|bmp|svg|avif|ico|tiff?|jfif|pjpeg|pjp)$/i.test(p)
}

/**
 * Build display metadata for a single file path. `size` is best-effort (0 when
 * the file can't be stat'd — e.g. a path on a disconnected drive); the renderer
 * hides the size label when it's 0.
 */
const fileEntryCache = new Map<string, FileEntry>()

function buildFileEntry(p: string): FileEntry {
  if (fileEntryCache.has(p)) return fileEntryCache.get(p)!
  let size = 0
  let isDirectory = false
  try {
    const st = statSync(p)
    size = st.size
    isDirectory = st.isDirectory()
  } catch {
    /* file missing / unreadable — size stays 0 */
  }
  const ext = isDirectory ? '' : (extname(p).slice(1) || '').toLowerCase()
  const name = pathBasename(p)
  const entry: FileEntry = {
    name,
    ext,
    size,
    isImage: !isDirectory && isImageExt(p),
    isDirectory
  }
  if (fileEntryCache.size > 500) fileEntryCache.clear()
  fileEntryCache.set(p, entry)
  return entry
}