// Package mode defines the contract the harness uses to host a single
// collect→brain→act unit. Focus and off-screen are implementations.
package mode

import (
	"context"
	"encoding/json"
	"time"

	"keel/internal/evidence"
)

// Mode is one collect→brain→act configuration. The harness runs at most one.
type Mode interface {
	// Kind identifies the mode ("focus", "offscreen").
	Kind() string
	// Command routes a surface-issued command into the mode. It returns an
	// error for illegal/invalid commands; the web layer maps it to HTTP.
	Command(ctx context.Context, name string, payload json.RawMessage) error
	// View projects the mode's current state for surfaces (JSON-marshalable).
	View() any
	// Active reports whether the mode still holds the harness. When it returns
	// false the harness releases the mode and goes idle.
	Active() bool
}

// EvidenceConsumer is implemented by modes that read the window sensor stream.
type EvidenceConsumer interface {
	OnWindow(evidence.WindowSnapshot)
}

// Expirer is implemented by modes with a server-authoritative deadline. Expire
// takes no context to match focus's existing Expire() error method, so focus
// satisfies this interface with zero changes to its tested surface.
type Expirer interface {
	Deadline() time.Time
	Expire() error
}

// Envelope is the surfacing wrapper: the active mode's kind plus its View().
type Envelope struct {
	ActiveMode string `json:"active_mode"` // "" = idle
	Mode       any    `json:"mode,omitempty"`
}