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.

28.2 KB
Raw Blame
/**
 * Reading & categorizing the system clipboard.
 *
 * Electron's `clipboard` API doesn't emit native change events, so we poll and
 * need to detect *what kind* of thing is on the clipboard each tick. The
 * priority is: files > image > html(rich) > text. We also pull a few "rich"
 * variants out of raw Windows formats (copied files arrive as FileNameW).
 */
import type { NativeImage } from 'electron'
import * as clipboard from './osClipboard'
import { execFile } from 'node:child_process'
import { promisify } from 'node:util'
import { existsSync } from 'node:fs'
import koffi from 'koffi'
import type { ClipboardImageSource, ItemData } from '../../shared/types'
import { isLinkText } from '../../shared/linkText'

let getSeqNum: (() => number) | null = null

/** Win32 calls for reading CF_HDROP in-process (see readFileDropListNative). */
interface HdropApi {
  open: (hWnd: number) => boolean
  close: () => boolean
  isAvailable: (format: number) => boolean
  getData: (format: number) => unknown
  dragQuery: (hDrop: unknown, index: number, buf: Buffer | null, cch: number) => number
}
let hdropApi: HdropApi | null = null

if (process.platform === 'win32') {
  try {
    const user32 = koffi.load('user32.dll')
    getSeqNum = user32.func('uint32 GetClipboardSequenceNumber()')
    try {
      const shell32 = koffi.load('shell32.dll')
      hdropApi = {
        open: user32.func('bool OpenClipboard(uintptr_t hWndNewOwner)'),
        close: user32.func('bool CloseClipboard()'),
        isAvailable: user32.func('bool IsClipboardFormatAvailable(uint32 format)'),
        getData: user32.func('void *GetClipboardData(uint32 uFormat)'),
        dragQuery: shell32.func('uint32 DragQueryFileW(void *hDrop, uint32 iFile, _Out_ uint16_t *lpszFile, uint32 cch)')
      }
    } catch (err) {
      console.error('[formats] Failed to load CF_HDROP APIs; file lists will use PowerShell:', err)
    }
  } catch (err) {
    console.error('[formats] Failed to load GetClipboardSequenceNumber from user32.dll:', err)
  }
}

export function getClipboardSequenceNumber(): number {
  if (getSeqNum) {
    try {
      return getSeqNum()
    } catch {
      return 0
    }
  }
  return 0
}
import { getSystemPowerShellPath, getWritableCwd } from '../main/powershell'
import { filterValidPaths } from '../main/pathValidation'
import { isStoreBuild } from '../main/config'

const execFileAsync = promisify(execFile)

/** Windows clipboard format name for a copied-file list. */
export const CF_FILE_LIST = 'FileNameW'

const CF_HDROP = 15

/**
 * Read every path of CF_HDROP in-process — the same data PowerShell's
 * GetFileDropList() returns, without spawning powershell.exe (measured
 * 250–300ms per copy, which is what made copied files appear late).
 * Returns null whenever the native read cannot answer, so the caller falls
 * back to the PowerShell path unchanged.
 */
async function readFileDropListNative(): Promise<string[] | null> {
  const api = hdropApi
  if (!api) return null
  for (let attempt = 0; attempt < 3; attempt++) {
    if (api.open(0)) {
      try {
        if (!api.isAvailable(CF_HDROP)) return null
        const hDrop = api.getData(CF_HDROP)
        if (!hDrop) return null
        const count = api.dragQuery(hDrop, 0xffffffff, null, 0)
        const paths: string[] = []
        for (let i = 0; i < count; i++) {
          const len = api.dragQuery(hDrop, i, null, 0)
          if (!len) continue
          const out = Buffer.alloc((len + 1) * 2)
          if (!api.dragQuery(hDrop, i, out, len + 1)) continue
          paths.push(out.toString('utf16le', 0, len * 2))
        }
        return paths.length ? paths : null
      } catch {
        return null
      } finally {
        try { api.close() } catch { /* ignore */ }
      }
    }
    // Another process holds the clipboard open (often Explorer finishing a
    // delayed render). Back off briefly without blocking the main thread.
    await new Promise((resolve) => setTimeout(resolve, 25))
  }
  return null
}

/**
 * Async version: reads the full list of copied file paths. CF_HDROP is read
 * in-process first; PowerShell GetFileDropList() remains the fallback. Both
 * return ALL selected files from a multi-file Explorer copy (FileNameW only
 * carries the first file as a legacy single-path fallback).
 *
 * Falls back to parsing the FileNameW UTF-16LE buffer directly if both are
 * unavailable or PowerShell times out.
 */
async function readFileListAsync(): Promise<string[] | null> {
  try {
    // First, confirm there is actually a file list on the clipboard before
    // reading it. FileNameW being present is sufficient signal.
    const buf = clipboard.readBuffer(CF_FILE_LIST)
    if (!buf || buf.length < 4) return null

    if (process.platform === 'win32') {
      const native = await readFileDropListNative()
      if (native) {
        const paths = filterValidPaths(native)
        if (paths.length > 0) return paths
      }
      try {
        const psPath = getSystemPowerShellPath()
        // Await the result so we actually get all paths — the previous
        // implementation fired execFile with a callback that returned from
        // the closure, not from readFileList(), so the result was dropped.
        const { stdout } = await execFileAsync(
          psPath,
          [
            '-NoProfile',
            '-NonInteractive',
            '-Command',
            'Add-Type -AssemblyName System.Windows.Forms; [System.Windows.Forms.Clipboard]::GetFileDropList()'
          ],
          { encoding: 'utf8', timeout: 2000, windowsHide: true, ...(isStoreBuild() ? { cwd: getWritableCwd() } : {}) }
        )
        if (stdout) {
          const paths = filterValidPaths(stdout.split(/\r?\n/).map((l) => l.trim()))
          if (paths.length > 0) return paths
        }
      } catch {
        // PowerShell timeout or locked clipboard fallback — parse buffer directly
      }
    }

    // Non-Windows or PowerShell fallback: parse the FileNameW buffer directly.
    // On Windows this will typically only return the first file, but it is
    // better than nothing when PowerShell is unavailable.
    const wide = buf.toString('utf16le')
    const parts = filterValidPaths(wide.split('\u0000').map((s) => s.trim()))
    return parts.length ? parts : null
  } catch {
    return null
  }
}

/** Fast, non-blocking check of FileNameW contents for clipboard signatures. */
function readFileListFast(): string[] | null {
  try {
    const buf = clipboard.readBuffer(CF_FILE_LIST)
    if (!buf || buf.length < 4) return null
    const wide = buf.toString('utf16le')
    const parts = wide.split('\u0000').map((s) => s.trim()).filter(Boolean)
    return parts.length ? parts : null
  } catch {
    return null
  }
}

/**
 * True when FileNameW currently holds at least one path.
 *
 * Cheap peek used by the watcher during the post-capture coalesce window.
 * Reads only FileNameW (not CF_BITMAP / FileContents), so it does not
 * retrigger Explorer's delayed-render pipeline.
 */
export function clipboardHasFileNameW(): boolean {
  try {
    const buf = clipboard.readBuffer(CF_FILE_LIST)
    return !!(buf && buf.length >= 4)
  } catch {
    return false
  }
}

/**
 * Content key for the file drop currently on the clipboard, matching
 * `contentSignature` for `kind: 'files'`.
 *
 * Uses FileNameW plus CF_UNICODETEXT (Explorer writes every selected path as
 * plain text). Does not request CF_BITMAP / FileContents, so it will not
 * retrigger delayed rendering.
 *
 * Closing an Explorer window sends WM_RENDERALLFORMATS and bumps the sequence
 * number without changing the path list — the watcher compares this key to
 * the last capture and ignores that flush.
 */
export function clipboardFilesContentKey(): string | null {
  try {
    const buf = clipboard.readBuffer(CF_FILE_LIST)
    if (!buf || buf.length < 4) return null
    const fromName = buf
      .toString('utf16le')
      .split('\u0000')
      .map((s) => s.trim())
      .filter(Boolean)
    if (!fromName.length) return null

    let paths = fromName
    try {
      const raw = clipboard.readText()
      if (raw) {
        const lines = raw
          .split(/\r?\n/)
          .map((s) => s.trim().replace(/^"(.*)"$/, '$1'))
          .filter(Boolean)
        if (lines.length >= fromName.length && lines.includes(fromName[0])) {
          paths = lines
        }
      }
    } catch {
      /* FileNameW only */
    }

    return `files|${paths.join('\n')}`
  } catch {
    return null
  }
}

/**
 * True when the clipboard is advertising a real file drop (Explorer, desktop,
 * etc.) even if the path list is not readable yet. FileGroupDescriptor alone
 * is NOT enough — browsers use that for "Copy Image" virtual files.
 */
function clipboardAdvertisesFileList(): boolean {
  if (clipboardHasFileNameW()) return true
  try {
    return clipboard.availableFormats().some((f) => {
      const l = f.toLowerCase()
      return l === 'filenamew' || l === 'filename' || l.includes('shell idlist')
    })
  } catch {
    return false
  }
}

/**
 * Build a `FileNameW` clipboard buffer.
 *
 * This is the reverse of `readFileList()`: UTF-16LE paths separated by NUL
 * chars, terminated with a double NUL. Writing this format lets the Windows
 * clipboard hold actual file *references* so that pasting into Explorer, Word,
 * etc. operates on the real files instead of pasting literal path strings.
 */
export function buildFileListBuffer(paths: string[]): Buffer {
  // Each path separated by NUL, then two trailing NULs to terminate the list.
  const joined = paths.join('\0') + '\0\0'
  return Buffer.from(joined, 'utf16le')
}

const URL_RE = /^(https?:\/\/|www\.)[^\s]+$/i
const COLOR_HEX_RE = /^#([0-9a-f]{3}|[0-9a-f]{6}|[0-9a-f]{8})$/i
const FILE_URL_RE = /file:\/\/\/?([^\s"'<>]+)/i

/** Turn a clipboard file:// URL into a local path if that file exists. */
export function localPathFromClipboardFileUrl(raw: string): string | null {
  const m = raw.match(FILE_URL_RE)
  if (!m) return null
  try {
    let decoded = decodeURIComponent(m[1].replace(/"/g, ''))
    if (/^[a-zA-Z]:[\\/]/.test(decoded) || decoded.startsWith('\\\\')) {
      decoded = decoded.replace(/\//g, '\\')
    } else if (/^[a-zA-Z]\//.test(decoded)) {
      decoded = decoded.replace(/^([a-zA-Z])\//, '$1:\\').replace(/\//g, '\\')
    }
    return existsSync(decoded) ? decoded : null
  } catch {
    return null
  }
}

export function extractClipboardImageFileName(text: string, html: string): string | undefined {
  const fromHtml = localPathFromClipboardFileUrl(html)
  if (fromHtml) {
    const base = fromHtml.replace(/^.*[\\/]/, '')
    if (base) return base
  }
  const fromText = localPathFromClipboardFileUrl(text)
  if (fromText) {
    const base = fromText.replace(/^.*[\\/]/, '')
    if (base) return base
  }
  const http = text.match(/^(https?:\/\/.+)\/([^/?#]+)$/i)
  if (http && /\.(png|jpe?g|gif|webp|bmp|svg|avif)$/i.test(http[2])) {
    try {
      return decodeURIComponent(http[2])
    } catch {
      return http[2]
    }
  }
  return undefined
}

export function detectClipboardImageSource(text: string, html: string): ClipboardImageSource {
  try {
    const formats = clipboard.availableFormats().map((f) => f.toLowerCase())
    if (formats.some((f) => /screenshot|snipping|screen\s*clip|screenclip/.test(f))) {
      return 'screenshot'
    }
    if (formats.some((f) => /filegroupdescriptor|filecontents|filenamew|shell idlist/.test(f))) {
      return 'image'
    }
  } catch {
    /* ignore */
  }

  if (localPathFromClipboardFileUrl(html) || localPathFromClipboardFileUrl(text)) return 'image'
  if (/^<img\b/i.test(html.trim()) || URL_RE.test(text.trim())) return 'image'

  const trimmed = text.trim()
  if (
    trimmed &&
    !URL_RE.test(trimmed) &&
    !trimmed.includes('\t') &&
    trimmed.split(/\r?\n/).filter(Boolean).length === 1 &&
    trimmed.length <= 200
  ) {
    return 'screenshot'
  }

  if (!trimmed && !html.trim()) return 'screenshot'
  return 'image'
}

/** Sensitive clipboard formats used by password managers and transient scripts. */
const IGNORED_FORMATS = [
  'ClipboardViewerIgnore',
  'Clipboard Viewer Ignore',
  'ExcludeClipboardContentFromMonitorProcessing',
  'org.nspasteboard.ConcealedType',
  'org.nspasteboard.AutoGeneratedType',
  'com.agilebits.onepassword',
  'com.apple.is-sensitive',
  'com.apple.pasteboard.concealed',
  'KeePassClipFormat',
  'com.bitwarden.concealed'
]

/** Read a DWORD (32-bit uint) from a clipboard format, if present. */
export function _getClipboardDword(format: string): number | undefined {
  try {
    const buf = clipboard.readBuffer(format)
    if (buf && buf.length >= 4) {
      return buf.readUInt32LE(0)
    }
    // If present but empty buffer, we can't return a number, return null to indicate presence without value
    if (buf && buf.length === 0) {
      return -1
    }
  } catch {
    // ignore
  }
  return undefined
}

/**
 * Windows registered clipboard format names are compared case-insensitively by
 * the OS, but `availableFormats()` returns whatever casing the registering app
 * used. So a privacy flag like `ExcludeClipboardContentFromMonitorProcessing`
 * may arrive in any casing — we must match it case-insensitively, otherwise
 * content a password manager / dictation tool explicitly marked "do not record"
 * still leaks into our history (and out of Windows' own Win+V history).
 */
function isIgnoredFormat(format: string): boolean {
  const lower = format.toLowerCase()
  return IGNORED_FORMATS.some((f) => f.toLowerCase() === lower)
}

/**
 * Checks whether the current clipboard content is marked as sensitive, confidential,
 * or transient (e.g. by password managers, dictation tools, or macro scripts)
 * and should be ignored by clipboard monitors.
 */
export function isClipboardExcluded(): boolean {
  const formats = clipboard.availableFormats()

  if (formats.some((f) => isIgnoredFormat(f))) {
    return true
  }

  // Explicitly check known privacy formats because Chromium often hides them from availableFormats()
  const checkExplicitExclusion = (format: string, isExcluded: (buf: Buffer) => boolean) => {
    try {
      const buf = clipboard.readBuffer(format)
      if (!buf || buf.length === 0) return false
      return isExcluded(buf)
    } catch {
      return false
    }
  }

  // CanIncludeInClipboardHistory: 0 means DO NOT include
  if (checkExplicitExclusion('CanIncludeInClipboardHistory', (buf) => buf.length >= 4 && buf.readUInt32LE(0) === 0)) {
    return true
  }

  // CanUploadToCloudClipboard: 0 means DO NOT include
  if (checkExplicitExclusion('CanUploadToCloudClipboard', (buf) => buf.length >= 4 && buf.readUInt32LE(0) === 0)) {
    return true
  }

  // ExcludeClipboardContentFromMonitorProcessing: non-zero means EXCLUDE
  if (checkExplicitExclusion('ExcludeClipboardContentFromMonitorProcessing', (buf) => buf.length >= 4 && buf.readUInt32LE(0) !== 0)) {
    return true
  }

  // Clipboard Viewer Ignore: presence of format with data means EXCLUDE
  if (checkExplicitExclusion('Clipboard Viewer Ignore', () => true)) {
    return true
  }

  return false
}

/**
 * Async snapshot of the current clipboard into a single ItemData, or null.
 *
 * Order matters: a file copy should win over its text fallback, an image wins
/** HTML kept on an item for rich paste. Larger blobs stall persist, IPC, and React. */
export const MAX_ITEM_HTML_CHARS = 32_768
const HEAVY_TEXT_CHARS = 8_192
const HEAVY_TEXT_LINES = 40

function countNewlines(s: string, limit: number): number {
  let n = 0
  for (let i = 0; i < s.length && n < limit; i++) {
    if (s.charCodeAt(i) === 10) n++
  }
  return n
}

function isHeavyTabularText(text: string): boolean {
  if (!text.includes('\t')) return false
  return text.length > HEAVY_TEXT_CHARS || countNewlines(text, HEAVY_TEXT_LINES) >= HEAVY_TEXT_LINES
}

/** Scan a short prefix only — Excel HTML for a large range can be many MB. */
function htmlLooksLikeRichDocument(html: string): boolean {
  if (!html) return false
  const head = html.length > 4096 ? html.slice(0, 4096) : html
  return /<table\b|<tr\b|<td\b|<th\b|google-sheets|data-sheets|urn:schemas-microsoft-com:office:spreadsheet|excel|<html\b|<body\b|<p\b|<pre\b|<code\b|<ul\b|<ol\b|<li\b/i.test(head)
}

/**
 * Normalize clipboard text the same way `readClipboard` stores it, so the
 * watcher can cheap-compare a late Explorer/Excel format against the last capture
 * without decoding HTML or bitmaps.
 */
export function normalizeClipboardText(rawText: string): string {
  return rawText.includes('\t') ? rawText.replace(/\r?\n+$/, '') : rawText.trim()
}

/** Plain-text snapshot for coalesce checks. Does not read HTML or images. */
export function clipboardTextContent(): string | null {
  try {
    const raw = clipboard.readText()
    if (!raw) return null
    const n = normalizeClipboardText(raw)
    return n || null
  } catch {
    return null
  }
}

/**
 * Helper to determine whether a clipboard payload containing an image and text
 * is intended as an image (e.g. Snipping Tool window capture, browser "Copy Image",
 * or screenshot tool) or as text (e.g. Excel/Google Sheets tabular data, rich text,
 * multiline documents, code).
 */
export function isScreenshotOrImageIntent(hasImage: boolean, rawText: string, rawHtml: string): boolean {
  if (!hasImage) return false
  if (!rawText) return true

  // Single bare image tag from browser "Copy Image" (e.g. <img src="...">)
  if (/^<img\b[^>]*>$/i.test(rawText) || /^<img\b[^>]*\/?>$/i.test(rawHtml)) return true

  // Single URL without any other text (browser "Copy Image" often sets image URL as text)
  if (URL_RE.test(rawText) && rawText.length < 500) return true

  // Spreadsheets (Excel, Google Sheets, Calc) & tabular text:
  // 1. Tab characters (\t) indicate column separators
  if (rawText.includes('\t')) return false

  // 2. Multiline text (multiple rows) indicates real tabular data, document paragraphs, or code
  const lines = rawText.split(/\r?\n/).map((l) => l.trim()).filter(Boolean)
  if (lines.length > 1) return false

  // 3. Spreadsheet HTML markup tags & rich office metadata (prefix only)
  if (htmlLooksLikeRichDocument(rawHtml)) return false

  // 4. If text is long (> 200 chars), it is a text document, not a window title
  if (rawText.length > 200) return false

  // Snipping tool window mode: single-line window title text <= 200 chars without tabs or HTML structure
  return true
}

/**
 * Format text and HTML data for clipboard write back.
 *
 * 1. Normalizes line breaks to Windows CRLF (\r\n). On Windows, Microsoft Excel and
 *    other spreadsheet applications use \r\n to separate table rows. If bare \n (LF)
 *    is used, Excel interprets the newline as an in-cell line feed (Alt+Enter) and
 *    pastes the entire multiline table into a SINGLE cell!
 *
 * 2. If the text contains tab characters (\t), it represents spreadsheet tabular cells.
 *    If no valid <table> HTML is provided (or if only non-table wrappers like
 *    <google-sheets-html-origin> <div> exist), we synthesize a standard HTML <table>
 *    so that spreadsheet apps (Excel, Google Sheets, Calc) and office apps (Word, Outlook)
 *    distribute rows and columns across the cell grid rather than dumping text into one cell.
 */
export function formatTabularDataForClipboard(text: string, rawHtml?: string): { text: string; html?: string } {
  if (!text) return { text: '', html: rawHtml && rawHtml.length <= MAX_ITEM_HTML_CHARS ? rawHtml : undefined }

  // Normalize all line breaks to CRLF (\r\n) for Windows
  const crlfText = text.replace(/\r?\n/g, '\r\n')
  const htmlIfSmall = rawHtml && rawHtml.length <= MAX_ITEM_HTML_CHARS ? rawHtml : undefined

  // Check if content has tab characters indicating column separators
  if (text.includes('\t')) {
    // If rawHtml already contains a standard table tag, use it — but never
    // paste megabytes of Excel CF_HTML back; TSV+CRLF is enough for the grid.
    if (htmlIfSmall && /<table\b[^>]*>/i.test(htmlIfSmall)) {
      return { text: crlfText, html: htmlIfSmall }
    }

    if (isHeavyTabularText(text)) {
      return { text: crlfText }
    }

    // Otherwise, generate a clean, standard HTML table from the TSV content
    const rows = text.split(/\r?\n/)
    const htmlRows = rows.map((row) => {
      const cells = row.split('\t').map((cell) => {
        const escaped = cell
          .replace(/&/g, '&amp;')
          .replace(/</g, '&lt;')
          .replace(/>/g, '&gt;')
          .replace(/"/g, '&quot;')
          .replace(/'/g, '&#39;')
        return `<td>${escaped}</td>`
      }).join('')
      return `<tr>${cells}</tr>`
    }).join('')

    const htmlTable = `<table border="0" cellpadding="0" cellspacing="0"><tbody>${htmlRows}</tbody></table>`
    return { text: crlfText, html: htmlTable }
  }

  return { text: crlfText, html: htmlIfSmall }
}

/**
 * Async snapshot of the current clipboard into a single ItemData, or null.
 *
 * Order matters: a file copy should win over its text fallback, an image wins
 * over nothing, otherwise we keep text (preferring HTML if it carries rich text).
 *
 * This is async because reading the full multi-file list from a Windows
 * Explorer copy requires a PowerShell round-trip (GetFileDropList).
 */
export async function readClipboard(): Promise<ItemData | null> {
  if (isClipboardExcluded()) {
    return null
  }

  // Files first — a file copy also places text on the clipboard, which we ignore.
  const files = await readFileListAsync()
  if (files && files.length) return { kind: 'files', paths: files }

  // Explorer advertises FileNameW / Shell IDList before the path list is
  // readable. Falling through to the preview bitmap would record a screenshot
  // of the first file, then a second files card when the paths arrive.
  if (clipboardAdvertisesFileList()) return null

  // Text first. Excel/Sheets copies of a large range put a huge CF_BITMAP of
  // the selection plus megabytes of CF_HTML. Decoding those on the UI thread
  // stalls the window; shipping the HTML through persist/IPC makes it jitter.
  const rawText = clipboard.readText()
  const trimmedText = rawText.trim()
  const heavyTable = isHeavyTabularText(rawText)
  const skipBitmap = rawText.includes('\t') || countNewlines(rawText, 2) >= 2

  let rawHtml = ''
  if (!heavyTable) {
    rawHtml = await clipboard.readHTML()
  }
  const trimmedHtml = rawHtml.trim()

  const localFromHtml = localPathFromClipboardFileUrl(trimmedHtml) || localPathFromClipboardFileUrl(trimmedText)
  if (localFromHtml) return { kind: 'files', paths: [localFromHtml] }

  let hasImage = false
  let img: NativeImage | null = null
  if (!skipBitmap) {
    img = await clipboard.readImage()
    hasImage = !img.isEmpty()
  }

  // Snipping Tool (Window mode, Freeform, Rectangular) or browser images:
  if (img && isScreenshotOrImageIntent(hasImage, trimmedText, trimmedHtml)) {
    const size = img.getSize()
    return {
      kind: 'image',
      imageId: '',
      width: size.width,
      height: size.height,
      bytes: 0,  // placeholder — ClipboardWatcher overwrites this with the actual PNG buffer length
      source: detectClipboardImageSource(trimmedText, trimmedHtml),
      fileName: extractClipboardImageFileName(trimmedText, trimmedHtml)
    }
  }

  // Text intent (Notepad, Word, VS Code text copy, Excel/Google Sheets tabular copy, rich HTML copy)
  if (trimmedText) {
    let html: string | undefined
    if (trimmedHtml && trimmedHtml !== trimmedText && rawHtml.length <= MAX_ITEM_HTML_CHARS) {
      html = rawHtml
    }

    const textToStore = normalizeClipboardText(rawText)

    // A link card: scheme, www., mailto:/tel: or a bare domain (shared/linkText)
    const isUrl = isLinkText(trimmedText)
    const isColor = COLOR_HEX_RE.test(trimmedText)

    return { kind: 'text', text: textToStore, html, isUrl, isColor }
  }

  // Fallback to image if no text
  if (hasImage && img) {
    const size = img.getSize()
    return {
      kind: 'image',
      imageId: '',
      width: size.width,
      height: size.height,
      bytes: 0,
      source: detectClipboardImageSource(trimmedText, trimmedHtml),
      fileName: extractClipboardImageFileName(trimmedText, trimmedHtml)
    }
  }

  return null
}

/**
 * A cheap signature string used to detect that the clipboard *changed* without
 * having to construct a full ItemData or encode images.
 *
 * Strategy:
 *  - Files   → the list of paths (totally stable, always unique per copy)
 *  - Images  → dimensions + a sampled FNV-1a hash of raw pixel bytes
 *  - Text    → the text content itself
 *
 * For images we use `nativeImage.toBitmap()` (raw BGRA, no codec) and walk
 * ~400 evenly-spaced bytes through it.  This is:
 *   - Fast:   no PNG encoding, O(400) byte reads regardless of image size
 *   - Stable: same clipboard content → same pixels → same hash on every poll
 *   - Unique: different images with the same resolution produce different pixel
 *             values in practice, so collisions are astronomically unlikely
 */
export async function clipboardSignature(): Promise<string> {
  const seq = getClipboardSequenceNumber()
  const seqPrefix = seq > 0 ? `seq:${seq}:` : ''

  if (isClipboardExcluded()) {
    return `${seqPrefix}excluded`
  }

  // If files are on the clipboard, their paths are the most stable fingerprint.
  // Use fast, non-blocking read to avoid spawning a child process during polling.
  const files = readFileListFast()
  if (files && files.length) {
    return `${seqPrefix}files:${files.join('\n')}`
  }

  const rawUntrimmed = clipboard.readText()
  // Spreadsheet copies carry a huge selection bitmap. Fingerprint the TSV
  // only — toBitmap() of a 1500-row range stalls the window.
  if (rawUntrimmed.includes('\t') || countNewlines(rawUntrimmed, 2) >= 2) {
    return `${seqPrefix}text:${normalizeClipboardText(rawUntrimmed)}`
  }

  const img = await clipboard.readImage()
  const hasImage = !img.isEmpty()
  const rawText = rawUntrimmed.trim()
  const rawHtml = (await clipboard.readHTML()).trim()

  if (isScreenshotOrImageIntent(hasImage, rawText, rawHtml)) {
    const size = img.getSize()
    const bitmap = img.toBitmap()  // raw BGRA — no encoding, just a memory copy

    // FNV-1a over ~400 evenly-spaced bytes.
    const step = Math.max(1, Math.floor(bitmap.length / 400))
    let hash = 0x811c9dc5 // FNV offset basis
    for (let i = 0; i < bitmap.length; i += step) {
      hash ^= bitmap[i]
      hash = Math.imul(hash, 0x01000193) >>> 0 // FNV prime, keep as uint32
    }

    return `${seqPrefix}image:${size.width}x${size.height}:${hash.toString(36)}`
  }

  // Text — the content itself is the fingerprint.
  if (rawText) {
    return `${seqPrefix}text:${rawText}`
  }

  // Fallback to image if no text
  if (hasImage) {
    const size = img.getSize()
    const bitmap = img.toBitmap()
    const step = Math.max(1, Math.floor(bitmap.length / 400))
    let hash = 0x811c9dc5
    for (let i = 0; i < bitmap.length; i += step) {
      hash ^= bitmap[i]
      hash = Math.imul(hash, 0x01000193) >>> 0
    }
    return `${seqPrefix}image:${size.width}x${size.height}:${hash.toString(36)}`
  }

  return `${seqPrefix}empty`
}

/** True if the text payload looks like a single URL. */
export function isUrlText(s: string): boolean {
  return isLinkText(s)
}

/**
 * Pure matcher: does a clipboard signature (as produced by
 * `clipboardSignature()`) represent exactly this item's content?
 *
 * CRITICAL: signatures carry a Win32 `seq:<n>:` prefix whenever
 * GetClipboardSequenceNumber() > 0 (i.e., virtually always on Windows). The
 * comparison MUST strip that prefix first — comparing the raw string against
 * a bare `text:<content>` made every text/link ownership check silently fail,
 * so deleting an item whose content still sat on the system clipboard never
 * cleared it (and the content could then be re-captured later, appearing to
 * "come back").
 *
 * Image matching keeps the dimension-prefix heuristic (avoids a full pixel
 * read); over-clearing when two same-dimension images are involved is the
 * documented, acceptable trade-off.
 */
export function signatureMatchesItem(sig: string, data: ItemData, fullText?: string): boolean {
  const bare = sig.replace(/^seq:\d+:/, '')
  switch (data.kind) {
    case 'text': {
      const body = fullText && fullText.length > 0 ? fullText : data.text
      if (bare === `text:${body}`) return true
      // Long items store only a 300-char preview; the OS clipboard still has the full string.
      if (data.hasFullPayload && data.text && bare.startsWith(`text:${data.text}`)) return true
      return false
    }
    case 'files':
      return bare === `files:${data.paths.join('\n')}`
    case 'image':
      return bare.startsWith(`image:${data.width}x${data.height}:`)
    case 'image-collection':
      return bare.startsWith('image:')
  }
}