port

type Cache[K comparable, V any] interface {
	// Get retrieves a value by key. Returns the value and true if found,
	// or the zero value and false if not found.
	Get(key K) (V, bool)

	// Set stores a value for the given key. If the cache is at capacity,
	// the least recently used entry may be evicted.
	Set(key K, value V)

	// Remove deletes a key from the cache.
	Remove(key K)

	// Len returns the number of items currently in the cache.
	Len() int
}

type Clipboard interface {
	// WriteText copies text to the clipboard.
	WriteText(ctx context.Context, text string) error

	// ReadText reads text from the clipboard.
	// Returns empty string if clipboard is empty or contains non-text data.
	ReadText(ctx context.Context) (string, error)

	// Clear clears the clipboard contents.
	Clear(ctx context.Context) error

	// HasText returns true if the clipboard contains text data.
	HasText(ctx context.Context) (bool, error)
}

type ColorPalette struct {
	Background     string `json:"background"`
	Surface        string `json:"surface"`
	SurfaceVariant string `json:"surface_variant"`
	Text           string `json:"text"`
	Muted          string `json:"muted"`
	Accent         string `json:"accent"`
	Border         string `json:"border"`
}

type ConfigMigrator interface {
	// CheckMigration checks if user config is missing any default keys.
	// Returns nil if no migration is needed (config file doesn't exist or is complete).
	CheckMigration() (*MigrationResult, error)

	// DetectChanges analyzes user config and returns all detected changes.
	// This provides a detailed diff-like view of what migration would do.
	DetectChanges() ([]KeyChange, error)

	// Migrate adds missing default keys and removes deprecated keys from the user's config file.
	// Returns the list of keys that were added/renamed/removed.
	Migrate() ([]string, error)

	// GetKeyInfo returns detailed information about a config key.
	GetKeyInfo(key string) KeyInfo

	// GetConfigFile returns the path to the user's config file.
	GetConfigFile() (string, error)
}

type ConfigSchemaProvider interface {
	// GetSchema returns all configuration keys with their metadata.
	GetSchema() []entity.ConfigKeyInfo
}

type ContentInjector interface {
	// InjectThemeCSS injects CSS variables into the page for theming.
	// The css parameter should contain CSS custom property declarations.
	InjectThemeCSS(ctx context.Context, css string) error
}

type DatabaseProvider interface {
	// DB returns the database connection, initializing it if necessary.
	// Returns an error if initialization fails.
	DB(ctx context.Context) (*sql.DB, error)

	// Close closes the database connection if it was initialized.
	Close() error

	// IsInitialized returns true if the database has been initialized.
	IsInitialized() bool
}

type DesktopIntegration interface {
	// GetStatus checks the current desktop integration state.
	GetStatus(ctx context.Context) (*DesktopIntegrationStatus, error)

	// InstallDesktopFile writes the desktop file to XDG applications directory.
	// Returns the path where the file was installed.
	// Idempotent: safe to call multiple times.
	InstallDesktopFile(ctx context.Context) (string, error)

	// InstallIcon writes the icon file to XDG icons directory.
	// Returns the path where the icon was installed.
	// Idempotent: safe to call multiple times.
	InstallIcon(ctx context.Context, svgData []byte) (string, error)

	// RemoveDesktopFile removes the desktop file from XDG applications directory.
	// Idempotent: returns nil if file doesn't exist.
	RemoveDesktopFile(ctx context.Context) error

	// RemoveIcon removes the icon file from XDG icons directory.
	// Idempotent: returns nil if file doesn't exist.
	RemoveIcon(ctx context.Context) error

	// SetAsDefaultBrowser sets dumber as the default web browser using xdg-settings.
	// Returns error if desktop file is not installed.
	SetAsDefaultBrowser(ctx context.Context) error

	// UnsetAsDefaultBrowser resets default browser if dumber is currently default.
	// Idempotent: returns nil if not currently default.
	UnsetAsDefaultBrowser(ctx context.Context) error
}

type DesktopIntegrationStatus struct {
	DesktopFileInstalled bool
	DesktopFilePath      string
	IconInstalled        bool
	IconFilePath         string
	IsDefaultBrowser     bool
	ExecutablePath       string
}

type DiffFormatter interface {
	// FormatChangesAsDiff returns changes formatted as a diff-like string for display.
	FormatChangesAsDiff(changes []KeyChange) string
}

type FileSystem interface {
	Exists(ctx context.Context, path string) (bool, error)
	IsDirectory(ctx context.Context, path string) (bool, error)
	GetSize(ctx context.Context, path string) (int64, error)
	RemoveAll(ctx context.Context, path string) error
}

type FindController interface {
	Search(text string, options FindOptions, maxMatches uint)
	CountMatches(text string, options FindOptions, maxMatches uint)
	SearchNext()
	SearchPrevious()
	SearchFinish()
	GetSearchText() string

	// Signal connections
	OnFoundText(callback func(matchCount uint)) uint32
	OnFailedToFindText(callback func()) uint32
	OnCountedMatches(callback func(matchCount uint)) uint32
	DisconnectSignal(id uint32)
}

type FindOptions struct {
	CaseInsensitive bool
	AtWordStarts    bool
	WrapAround      bool
}

type GPUVendor string

type IdleInhibitor interface {
	// Inhibit increments the inhibit refcount. First call activates inhibition.
	// Safe to call multiple times (refcounted).
	Inhibit(ctx context.Context, reason string) error

	// Uninhibit decrements the refcount. When zero, releases inhibition.
	// Safe to call even if not currently inhibited (no-op).
	Uninhibit(ctx context.Context) error

	// IsInhibited returns true if currently inhibiting idle.
	IsInhibited() bool

	// Close releases any held resources. Should be called on application shutdown.
	Close() error
}

type KeyChange struct {
	Type     KeyChangeType // Type of change
	OldKey   string        // Old key name (for removed/renamed)
	NewKey   string        // New key name (for added/renamed)
	OldValue string        // Old value (for renamed/consolidated)
	NewValue string        // New/default value
}

type KeyChangeType int

type KeyInfo struct {
	// Key is the dot-notation key path (e.g., "update.enable_on_startup").
	Key string
	// Type is the Go type of the value (e.g., "bool", "int", "string").
	Type string
	// DefaultValue is a string representation of the default value.
	DefaultValue string
}

type LoadEvent int

type MediaDiagnostics interface {
	// RunDiagnostics checks GStreamer plugins and VA-API availability.
	RunDiagnostics(ctx context.Context) *MediaDiagnosticsResult
}

type MediaDiagnosticsResult struct {
	// GStreamer availability
	GStreamerAvailable bool

	// GStreamer plugins
	HasVAPlugin      bool // gst-plugins-bad VA (modern stateless decoders)
	HasVAAPIPlugin   bool // gstreamer-vaapi (legacy)
	HasNVCodecPlugin bool // nvcodec for NVIDIA

	// Detected hardware decoders
	AV1Decoders  []string
	H264Decoders []string
	H265Decoders []string
	VP9Decoders  []string

	// VA-API info
	VAAPIAvailable bool
	VAAPIDriver    string
	VAAPIVersion   string

	// Summary
	HWAccelAvailable bool
	AV1HWAvailable   bool
	Warnings         []string
}

type MigrationResult struct {
	// MissingKeys contains the keys that exist in defaults but not in user config.
	MissingKeys []string
	// ConfigFile is the path to the user's config file.
	ConfigFile string
}

type Notification interface {
	// Show displays a notification with the given message and type.
	// Duration is in milliseconds; pass 0 for default duration.
	// Returns an ID that can be used to dismiss the notification.
	Show(ctx context.Context, message string, notifType NotificationType, durationMs int) NotificationID

	// ShowZoom displays a special zoom level notification.
	// These typically appear in a fixed position and auto-dismiss.
	ShowZoom(ctx context.Context, zoomPercent int) NotificationID

	// Dismiss removes a specific notification by ID.
	Dismiss(ctx context.Context, id NotificationID)

	// Clear removes all displayed notifications.
	Clear(ctx context.Context)
}

type NotificationID string

type NotificationType int

type PkgConfigError struct {
	Kind    PkgConfigErrorKind
	Package string
	Output  string
	Err     error
}

type PkgConfigErrorKind string

type PopupRequest struct {
	TargetURI     string
	FrameName     string // e.g., "_blank", custom name, or empty
	IsUserGesture bool
	ParentViewID  WebViewID
}

type RenderingEnvManager interface {
	// DetectGPUVendor identifies the primary GPU vendor from system info.
	// Uses /sys/class/drm/card*/device/vendor as primary detection method.
	DetectGPUVendor(ctx context.Context) GPUVendor

	// ApplyEnvironment sets all rendering environment variables.
	// Must be called before any GTK/GStreamer initialization.
	ApplyEnvironment(ctx context.Context, settings RenderingEnvSettings) error

	// GetAppliedVars returns a map of environment variables that were set.
	// Useful for logging and debugging.
	GetAppliedVars() map[string]string
}

type RenderingEnvSettings struct {
	// --- GStreamer settings (from MediaConfig) ---
	// ForceVSync enables vertical sync for video playback.
	ForceVSync bool
	// GLRenderingMode controls OpenGL API selection: "auto", "gles2", "gl3", "none".
	GLRenderingMode string
	// GStreamerDebugLevel sets GStreamer debug verbosity (0-5).
	GStreamerDebugLevel int
	// VideoBufferSizeMB sets buffer size in megabytes for video streaming.
	VideoBufferSizeMB int
	// QueueBufferTimeSec sets queue buffer time in seconds for prebuffering.
	QueueBufferTimeSec int

	// --- WebKit compositor settings (from RenderingConfig) ---
	DisableDMABufRenderer  bool
	ForceCompositingMode   bool
	DisableCompositingMode bool

	// --- GTK/GSK settings (from RenderingConfig) ---
	GSKRenderer    string
	DisableMipmaps bool
	PreferGL       bool

	// --- Debug settings ---
	ShowFPS      bool
	SampleMemory bool
	DebugFrames  bool
}

type RuntimeVersionProbe interface {
	PkgConfigModVersion(ctx context.Context, pkgName string, prefix string) (string, error)
}

type SearchShortcut struct {
	URL         string `json:"url"`
	Description string `json:"description"`
}

type SessionLogConfig struct {
	Level         string
	Format        string
	TimeFormat    string
	LogDir        string
	WriteToStderr bool
	EnableFileLog bool
}

type SessionLogger interface {
	CreateLogger(ctx context.Context, sessionID entity.SessionID, cfg SessionLogConfig) (zerolog.Logger, func(), error)
}

type SessionSpawner interface {
	// SpawnWithSession starts a new dumber instance to restore a session.
	SpawnWithSession(sessionID entity.SessionID) error
}

type TabListProvider interface {
	// GetTabList returns the current tab list state.
	GetTabList() *entity.TabList
	// GetSessionID returns the current session ID.
	GetSessionID() entity.SessionID
}

type Texture interface {
	// GoPointer returns the underlying C pointer for GTK interop.
	GoPointer() uintptr
}

type UpdateApplier interface {
	// CanSelfUpdate checks if the current binary is writable by the current user.
	// Returns true if auto-update is possible, false if user lacks write permission.
	CanSelfUpdate(ctx context.Context) bool

	// GetBinaryPath returns the path to the currently running binary.
	GetBinaryPath() (string, error)

	// StageUpdate prepares the new binary to be applied on exit.
	// The staged update will be applied when ApplyOnExit is called.
	StageUpdate(ctx context.Context, newBinaryPath string) error

	// HasStagedUpdate checks if there is an update staged and ready to apply.
	HasStagedUpdate(ctx context.Context) bool

	// ApplyOnExit replaces the current binary with the staged update.
	// This should be called during graceful shutdown.
	// Returns the path to the backup of the old binary.
	ApplyOnExit(ctx context.Context) (backupPath string, err error)

	// ClearStagedUpdate removes any staged update without applying it.
	ClearStagedUpdate(ctx context.Context) error
}

type UpdateChecker interface {
	// CheckForUpdate compares the current version with the latest available release.
	// Returns update info including whether a newer version is available.
	CheckForUpdate(ctx context.Context, currentVersion string) (*entity.UpdateInfo, error)
}

type UpdateDownloader interface {
	// Download fetches the update archive to the specified destination directory.
	// Returns the path to the downloaded archive file.
	Download(ctx context.Context, downloadURL string, destDir string) (archivePath string, err error)

	// Extract extracts the binary from the downloaded archive.
	// Returns the path to the extracted binary.
	Extract(ctx context.Context, archivePath string, destDir string) (binaryPath string, err error)
}

type WebUIAppearanceConfig struct {
	SansFont        string       `json:"sans_font"`
	SerifFont       string       `json:"serif_font"`
	MonospaceFont   string       `json:"monospace_font"`
	DefaultFontSize int          `json:"default_font_size"`
	ColorScheme     string       `json:"color_scheme"`
	LightPalette    ColorPalette `json:"light_palette"`
	DarkPalette     ColorPalette `json:"dark_palette"`
}

type WebUIConfig struct {
	Appearance          WebUIAppearanceConfig     `json:"appearance"`
	DefaultUIScale      float64                   `json:"default_ui_scale"`
	DefaultSearchEngine string                    `json:"default_search_engine"`
	SearchShortcuts     map[string]SearchShortcut `json:"search_shortcuts"`
}

type WebUIConfigSaver interface {
	SaveWebUIConfig(ctx context.Context, cfg WebUIConfig) error
}

type WebView interface {
	// ID returns the unique identifier for this WebView.
	ID() WebViewID

	// LoadURI navigates to the specified URI.
	LoadURI(ctx context.Context, uri string) error

	// LoadHTML loads HTML content with an optional base URI for relative links.
	LoadHTML(ctx context.Context, content, baseURI string) error

	// Reload reloads the current page.
	Reload(ctx context.Context) error

	// ReloadBypassCache reloads the current page, bypassing cache.
	ReloadBypassCache(ctx context.Context) error

	// Stop stops the current page load.
	Stop(ctx context.Context) error

	// GoBack navigates back in history.
	// Returns error if back navigation is not possible.
	GoBack(ctx context.Context) error

	// GoForward navigates forward in history.
	// Returns error if forward navigation is not possible.
	GoForward(ctx context.Context) error

	// State returns the current WebView state as a snapshot.
	State() WebViewState

	// URI returns the current URI.
	URI() string

	// Title returns the current page title.
	Title() string

	// IsLoading returns true if a page is currently loading.
	IsLoading() bool

	// EstimatedProgress returns the load progress (0.0 to 1.0).
	EstimatedProgress() float64

	// CanGoBack returns true if back navigation is available.
	CanGoBack() bool

	// CanGoForward returns true if forward navigation is available.
	CanGoForward() bool

	// SetZoomLevel sets the zoom level (1.0 = 100%).
	SetZoomLevel(ctx context.Context, level float64) error

	// GetZoomLevel returns the current zoom level.
	GetZoomLevel() float64

	// GetFindController returns the find controller for text search.
	// Returns nil if find is not supported.
	GetFindController() FindController

	// SetCallbacks registers callback handlers for WebView events.
	// Pass nil to clear all callbacks.
	SetCallbacks(callbacks *WebViewCallbacks)

	// IsFullscreen returns true if the WebView is currently in fullscreen mode.
	IsFullscreen() bool

	// IsPlayingAudio returns true if the WebView is currently playing audio.
	IsPlayingAudio() bool

	// IsDestroyed returns true if the WebView has been destroyed.
	IsDestroyed() bool

	// Destroy releases all resources associated with this WebView.
	// After calling Destroy, the WebView should not be used.
	Destroy()
}

type WebViewCallbacks struct {
	// OnLoadChanged is called when load state changes.
	OnLoadChanged func(event LoadEvent)
	// OnTitleChanged is called when the page title changes.
	OnTitleChanged func(title string)
	// OnURIChanged is called when the URI changes.
	OnURIChanged func(uri string)
	// OnProgressChanged is called during page load with progress 0.0-1.0.
	OnProgressChanged func(progress float64)
	// OnFaviconChanged is called when the page favicon changes.
	// The parameter is a *gdk.Texture (passed as Texture interface to avoid GTK import in port layer).
	OnFaviconChanged func(favicon Texture)
	// OnClose is called when the WebView requests to close.
	OnClose func()
	// OnCreate is called when a popup window is requested.
	// Return a WebView to allow the popup, or nil to block it.
	OnCreate func(request PopupRequest) WebView
	// OnReadyToShow is called when a popup WebView is ready to display.
	OnReadyToShow func()
	// OnLinkHover is called when hovering over a link, image, or media element.
	// The uri parameter contains the target URL, or empty string when leaving.
	OnLinkHover func(uri string)
}

type WebViewFactory interface {
	// Create creates a new WebView instance.
	Create(ctx context.Context) (WebView, error)

	// CreateRelated creates a WebView that shares session/cookies with parent.
	// This is required for popup windows to maintain authentication state.
	// Popup WebViews bypass the pool since they must be related to a specific parent.
	CreateRelated(ctx context.Context, parentID WebViewID) (WebView, error)
}

type WebViewID uint64

type WebViewPool interface {
	// Acquire obtains a WebView from the pool or creates a new one.
	// The context can be used for cancellation.
	Acquire(ctx context.Context) (WebView, error)

	// Release returns a WebView to the pool for reuse.
	// The WebView will be reset to a blank state.
	// If the pool is full, the WebView will be destroyed.
	Release(wv WebView)

	// Prewarm creates WebViews in the background to populate the pool.
	// Pass count <= 0 to use the default prewarm count.
	Prewarm(count int)

	// Size returns the current number of available WebViews in the pool.
	Size() int

	// Close shuts down the pool and destroys all pooled WebViews.
	Close()
}

type WebViewState struct {
	URI       string
	Title     string
	IsLoading bool
	Progress  float64 // 0.0 to 1.0
	CanGoBack bool
	CanGoFwd  bool
	ZoomLevel float64
}

type XDGPaths interface {
	ConfigDir() (string, error)
	DataDir() (string, error)
	StateDir() (string, error)
	CacheDir() (string, error)

	FilterJSONDir() (string, error)
	FilterStoreDir() (string, error)
	FilterCacheDir() (string, error)

	// ManDir returns the user man page directory (man1 section).
	// Typically $XDG_DATA_HOME/man/man1 or ~/.local/share/man/man1.
	ManDir() (string, error)
}