plugin

type ConfigField struct {
	Key     string           `json:"key"`
	Label   string           `json:"label"`
	Type    FieldType        `json:"type"`
	Default any              `json:"default,omitempty"`
	Options []FieldOption    `json:"options,omitempty"` // enum only
	Min     *int             `json:"min,omitempty"`     // int only
	Max     *int             `json:"max,omitempty"`     // int only
	Help    string           `json:"help,omitempty"`
	ShowIf  *ShowIfCondition `json:"show_if,omitempty"`
}

type ConfigSchema struct {
	Fields []ConfigField `json:"fields"`
}

type Descriptor struct {
	Name        string       `json:"name"`                // Human-readable name (e.g., "CPU Temperature")
	Version     string       `json:"version"`             // Semantic version (e.g., "1.0.0")
	Author      string       `json:"author"`              // Author name or organization
	Description string       `json:"description"`         // Brief description of functionality
	Icon        string       `json:"icon"`                // Default icon identifier (Font Awesome or emoji)
	RefreshMs   int          `json:"refresh_ms"`          // Recommended refresh interval in milliseconds
	HasGraph    bool         `json:"has_graph,omitempty"` // True if this plugin renders a sparkline/graph
	Schema      ConfigSchema `json:"config_schema"`       // Declared configurable fields
}

type DetailPayload struct {
	// ZoneID identifies which zone this detail belongs to.
	ZoneID string `json:"zone_id"`

	// Title is human-readable metadata about this detail view (e.g. "Jersey City — 7-Day Forecast").
	// Not rendered by the core; plugins may use it for logging or future accessibility support.
	Title string `json:"title,omitempty"`

	// RawFrame is a pre-rendered 640×48 RGBA pixel buffer (width×height×4 bytes, row-major).
	// The core blits this directly to the display. Plugins are responsible for all layout
	// and rendering. Use the gg (fogleman/gg) or image/draw packages to produce this.
	RawFrame []byte `json:"raw_frame,omitempty"`
}

type DetailTapper interface {
	OnDetailTap(x, y int) (bool, error)
}

type ErrLoadSparkOutOfRange struct {
	Index int
	Value float32
}

type ErrSparkOutOfRange struct {
	Index int
	Value float32
}

type ExecPlugin struct {
	Impl Plugin
}

type FieldOption struct {
	Value string `json:"value"`
	Label string `json:"label"`
}

type FieldType string

type GraphType string

type LabelPosition string

type Payload struct {
	// Title - Optional zone header (usually omitted for space)
	Title string `json:"title,omitempty"`

	// Primary - Main value displayed (14-16px bold)
	// Examples: "42°C", "↓58 MB/s", "Now Playing"
	Primary string `json:"primary"`

	// Secondary - Subtext or context (10px, muted color)
	// Examples: "Load 31%", "Albany ☀️", "Radiohead"
	Secondary string `json:"secondary,omitempty"`

	// Spark - Sparkline data (normalized 0.0-1.0, max 60 points)
	// Rendered as small bars/line at bottom of zone
	Spark []float32 `json:"spark,omitempty"`

	// GraphType - How to render sparkline data: "sparkline", "bar", "area"
	// Defaults to "sparkline" if empty
	GraphType GraphType `json:"graph_type,omitempty"`

	// Severity - Visual severity indicator: "ok", "warn", "crit"
	// Affects primary text color
	Severity Severity `json:"severity,omitempty"`

	// TTL - Cache lifetime
	// Host will re-use this payload until TTL expires
	TTL time.Duration `json:"ttl,omitempty"`

	// Icon - Icon override (Font Awesome name or emoji)
	Icon string `json:"icon,omitempty"`

	// Progress - Progress bar value (0.0-1.0)
	// Rendered as horizontal bar (for media playback, etc.)
	Progress float32 `json:"progress,omitempty"`

	// Timestamp - When this payload was generated
	Timestamp time.Time `json:"timestamp,omitempty"`

	// LineSpacing - Spacing between lines for multi-line Primary text (in pixels)
	// Defaults to 24 if not specified. Use higher values (e.g., 28-30) for more breathing room
	LineSpacing int `json:"line_spacing,omitempty"`

	// LabelPosition - Where to position the secondary label relative to primary
	// Defaults to "below" if not specified. Options: "below", "right"
	LabelPosition LabelPosition `json:"label_position,omitempty"`

	// LabelOffsetX - Horizontal offset for label positioning (in pixels)
	// Positive moves right, negative moves left. Applied after base positioning.
	LabelOffsetX int `json:"label_offset_x,omitempty"`

	// LabelOffsetY - Vertical offset for label positioning (in pixels)
	// Positive moves down, negative moves up. Applied after base positioning.
	LabelOffsetY int `json:"label_offset_y,omitempty"`

	// Value - Numeric or short string value (displayed large, left-aligned).
	// Replaces the fused Primary field for structured payloads.
	// If set, Value+ValueUnit are rendered together; Primary is ignored.
	Value string `json:"value,omitempty"`

	// ValueUnit - Unit suffix rendered smaller and dimmer after Value.
	// Examples: "°C", "%", "MB/s"
	ValueUnit string `json:"value_unit,omitempty"`

	// Span - Number of contiguous zone slots this payload occupies (1–6).
	// A value of 3 means the zone expands to 300px wide at render time.
	// Defaults to 1.
	Span int `json:"span,omitempty"`

	// Expandable - True if tapping this zone can show a detail view.
	Expandable bool `json:"expandable,omitempty"`

	// LoadSpark - Secondary sparkline data for combo graph type.
	// Used alongside Spark to render e.g. temp+load on the same graph.
	LoadSpark []float32 `json:"load_spark,omitempty"`

	// NormalizeGraph - If true, graph data is normalized to fill from baseline
	// Set to true for graphs where relative changes matter (network bandwidth)
	// Set to false for graphs where absolute values matter (temperatures)
	// Defaults to false (no normalization, show absolute 0-1 values)
	NormalizeGraph bool `json:"normalize_graph,omitempty"`

	// GraphBgOpacity - Background fill opacity for graphs (0-100)
	// 0 = fully transparent, 100 = fully opaque
	// If not set, uses theme default (typically very low for subtlety)
	GraphBgOpacity int `json:"graph_bg_opacity,omitempty"`

	// GraphLineOpacity - Line opacity for graphs (0-100)
	// 0 = fully transparent, 100 = fully opaque
	// If not set, uses theme default (typically low for subtlety)
	GraphLineOpacity int `json:"graph_line_opacity,omitempty"`

	// Caption - Small accent-colored annotation rendered between the label and the
	// sparkline (info-blue, caption font size). Intended for rate readouts like
	// "↓222K ↑221K" in the network zone. Ignored when no Spark data is present.
	Caption string `json:"caption,omitempty"`

	// RawFrame - Pre-rendered RGBA pixel data (width×height×4 bytes, row-major).
	// When set, the renderer skips all text/graph layout and blits these pixels
	// directly. Width and height must match the zone dimensions exactly.
	// Primary may be empty when RawFrame is set.
	RawFrame []byte `json:"raw_frame,omitempty"`
}

type Plugin interface {
	// Describe returns plugin metadata and config schema.
	Describe() (Descriptor, error)

	// Sample returns current data payload.
	Sample() (Payload, error)

	// Configure applies per-zone plugin configuration.
	// Called once at startup (with zone's stored config) and on every live edit.
	Configure(cfg map[string]any) error
}

type Severity string

type ShowIfCondition struct {
	Key   string `json:"key"`
	NotEq string `json:"not_eq"`
}

type Tapper interface {
	OnTap() (DetailPayload, error)
}