// Package clipboard provides unified clipboard read/write across Linux, Windows, and macOS.
//
// On Linux, it auto-detects X11 (xclip) vs Wayland (wl-clipboard) by checking
// $XDG_SESSION_TYPE and verifying the required binaries at initialization time.
// On Windows, it uses the Win32 clipboard API via syscall (no CGo).
// On macOS, it shells out to pbpaste / pbcopy.
//
// Each platform file defines its own New() constructor using //go:build tags.
package clipboard

import "errors"

// ErrNoImage is returned by ImageClipboard.ReadImage when the clipboard holds
// no image data. It is a normal condition, not an error.
var ErrNoImage = errors.New("clipboard: no image")

// Clipboard is the cross-platform clipboard interface.
type Clipboard interface {
	// Read returns the current text content of the clipboard.
	// Returns an empty string if the clipboard is empty or contains non-text data.
	Read() (string, error)

	// Write sets the clipboard text content.
	Write(text string) error
}

// ImageClipboard is an optional interface implemented by platforms that can
// read and write image data from the clipboard. Use a type assertion to detect
// support: `if ic, ok := cb.(clipboard.ImageClipboard); ok { ... }`.
type ImageClipboard interface {
	// ReadImage returns the MIME type and raw bytes of the clipboard image.
	// It returns ErrNoImage if the clipboard holds no image.
	ReadImage() (mime string, data []byte, err error)

	// WriteImage sets the clipboard image content.
	WriteImage(mime string, data []byte) error
}