ui

type ClickableRegion struct {
	// contains filtered or unexported fields
}

type ConnectAction uint8

type ConnectController interface {
	ListConnectTargets(context.Context) ([]ConnectTarget, error)
}

type ConnectRestartIntent struct {
	Target string
	Action ConnectAction
	// ResumeSessionID is retained only for same-target recovery actions. Main
	// re-checks ownership through GetSession before adopting it.
	ResumeSessionID string
}

type ConnectTarget struct {
	Target   string
	Issuer   string
	ClientID string
	Audience string
}

type Converser interface {
	OpenConverse(ctx context.Context) (*client.Stream, error)
}

type Deps struct {
	Session    SessionCreator
	Conv       Converser
	MCP        client.MCP             // MCP/ToolHive inventory + resources/prompts; nil disables the overlay
	Cmds       client.Commander       // slash-command discovery for the input palette; nil disables it
	Guardrails client.GuardrailClient // contextual coverage and live-only review detail; nil disables /guardrails
	// ShowBenignHookNotices keeps exact known-benign contextual guardrail review
	// notices, including their live detail, visible while details are collapsed.
	ShowBenignHookNotices bool
	// ServerInfo reads the safe build and composition identities when /diagnostics is invoked against a remote server.
	ServerInfo ServerInfoGetter
	// ServerImpl is the locally-known embedded server family. It is used without
	// an RPC when Embedded is true.
	ServerImpl         string
	Skills             client.SkillLister      // skills-inventory discovery for the /skills panel; nil disables it
	Agents             client.AgentLister      // agent-definition discovery for the /agents panel; nil disables it
	Soul               client.SoulFetcher      // soul (persona) inspection for the /soul panel; nil disables it
	UserModel          client.UserModelLister  // user-model inspection for the /memory panel; nil disables it
	Reflections        client.ReflectionClient // proposal review and explicit reflection; nil disables it
	Dream              client.DreamClient      // manual memory consolidation review; nil disables /dream
	Compactor          client.SessionCompactor // out-of-band session compaction; nil disables /compact
	ExecutionTemplates interface {
		ListExecutionTemplates(context.Context) (client.ExecutionTemplateInventory, error)
	}
	Models    client.ModelLister    // selectable-model discovery for the /models picker; nil disables it
	Worktrees client.WorktreeLister // worktree discovery for the /worktrees overlay (issue #102); nil disables it
	// Sched is the schedule discovery + management surface for the /schedule overlay
	// (issue #234); nil disables it (the overlay is honestly absent). The overlay can
	// create/inspect/pause/resume/fire-now on any store-backed server; auto-firing on
	// a cadence is the server's tick loop (ON by default on a schedule-capable store;
	// `mecated --no-scheduler` opts out).
	Sched client.ScheduleLister
	// Sessions is the stored-session inventory surface for the /sessions picker
	// (issue #245); nil disables it (the overlay is honestly absent). It is
	// the lister the picker calls to enumerate stored sessions. Unlike the
	// caps-gated overlays it is NOT gated on a ServerCapabilities bit — the picker
	// is available whenever a lister + authoritative transcript loader are wired
	// (a no-FS/cloud server with a durable SessionStore still has stored sessions).
	Sessions client.SessionPager
	// StorageHealth is the authenticated aggregate health surface. The capability
	// bit controls whether the Sessions panel advertises its maintenance tab.
	StorageHealth client.StorageHealthFetcher
	// Cleanup is the destructive storage-management seam.
	Cleanup client.SessionCleaner
	// SessionManagement mutates stored main-chat metadata. nil leaves rename/delete
	// undiscoverable even if a custom lister advertises those capabilities.
	SessionManagement client.SessionManager
	// Transcript is the authoritative snapshot-derived conversation surface used
	// by /sessions for both continuation and read-only inspection. Event replay is
	// optional activity and never substitutes for this seam.
	Transcript client.SessionTranscripter
	// Replayer is the optional durable-event-log activity surface used by live
	// delivery catch-up. It never attests conversation completeness.
	Replayer client.SessionReplayer
	// LiveStream is the LIVE per-session event feed: the server
	// pushes fire-result delivery notes for the active session as they occur. The ui
	// holds the interface (not a *Client) so it is injectable with a fake for offline
	// tests. nil disables the live bridge (the ui still renders deliveries via the
	// replay on a session switch/reload, just not live). *Client satisfies it.
	LiveStream client.LiveStreamer
	// PendingApprovals owns exact-run watch and control operations for an exact
	// startup recovery. It is unused for ordinary continuation.
	PendingApprovals PendingApprovalController
	// MCPAuthorization is the distinct browser authorization surface. It never
	// shares the permission-approval stream or controls.
	MCPAuthorization client.MCPAuthorizationController
	// WorkspaceEnrollment is the distinct pre-prompt whole-bundle control.
	WorkspaceEnrollment client.WorkspaceEnrollmentController
	// OpenURL opens a presentation URL obtained only through MCPAuthorization.
	// Composition owns the OS integration; nil leaves the action unavailable.
	OpenURL func(context.Context, string) error
	// SelectionStore persists the picked model (last-used). nil disables persistence
	// (the pick still applies to the next create this run, just isn't remembered).
	SelectionStore SelectionStore
	Learning       LearningSettings // operator mecatl settings.yaml; nil disables /learning
	// Connect lists public saved remote-target metadata. It cannot authenticate,
	// launch a browser, or expose credentials; selection exits via ConnectRestartIntent.
	Connect ConnectController
	// ConnectOpen reopens /connect after a host-side login/dial failure. ConnectError
	// is host-sanitized display text only.
	ConnectOpen  bool
	ConnectError string
	// ConnectReason controls the auth-recovery affordance without exposing a
	// transport error or credential to the renderer.
	ConnectReason          client.AuthReason
	ConnectTarget          string
	ConnectResumeSessionID string
	// BearerBacked records credential provenance for classifying server auth
	// responses. It contains no credential material.
	BearerBacked bool
	// InitialModel is the persisted selection loaded at launch (composition-side,
	// from the state file). The picker seeds its active selection from it (the ●
	// marker) and the startup CreateSession carries it — AFTER the connect-time
	// ListModels reconcile clears it if its PROVIDER is no longer available. The
	// reconcile is provider-level only (issue #41): a model absent from the (possibly
	// embedded-floor) snapshot is still carried verbatim — the server validates it,
	// and a rejection falls back to the default loudly (connectFallbackMsg).
	InitialModel client.ModelSelection
	// WorkspaceDefault / GlobalDefault are the SEPARATE raw state-file values loaded at
	// launch (composition-side): the per-workspace entry (zero when none — see
	// WorkspaceDefaultSet) and the global `default:` block. They are display-only
	// provenance inputs for the /models picker's "current: <model> (<provenance>)"
	// line and the ★ global-default row marker — the ui derives a best-effort label
	// from client-held state, never a server round-trip. (InitialModel is the RESOLVED
	// Load result = workspace-or-global; these are the un-collapsed pieces.)
	WorkspaceDefault    client.ModelSelection
	WorkspaceDefaultSet bool
	GlobalDefault       client.ModelSelection
	// Clipboard reads the OS clipboard for ctrl+v paste (image-first, text-fallback).
	// nil cleanly disables ctrl+v image paste (same convention as nil MCP/Cmds);
	// main.go populates it with client.NewClipboard().
	Clipboard client.Clipboard
	Theme     theme.Theme

	// ThemeAutoDetect enables the terminal-background light/dark auto-detect:
	// composition sets it true only when no explicit --theme/
	// MECATUI_THEME was supplied AND stdout is a real TTY (never on redirected
	// output, which must never see the OSC background-colour query). When true,
	// Init requests the terminal's background color (tea.RequestBackgroundColor)
	// and a light response switches the active theme to the built-in "solar"
	// theme; a dark or absent response keeps Theme as given. Explicit theme
	// selection always wins — this field is simply never set true then.
	ThemeAutoDetect bool

	// ProbeKeyboardCapability bounds how long the prompt's newline hint trusts its
	// optimistic chord: composition sets it true only when stdout is a real TTY.
	// Bubble Tea asks every terminal for its keyboard enhancements on the first
	// render, but a terminal that does not implement them answers nothing at all,
	// so an unanswered query is the only signal there is and it needs a deadline.
	// There is nothing to answer on redirected output or in a test harness, so the
	// deadline is not armed there and the hint keeps its optimistic chord. An
	// explicit negative reply still corrects the hint immediately, armed or not.
	// See keyboardProbeDeadline for why an unanswered query is treated as
	// unconfirmed rather than as a proven negative.
	ProbeKeyboardCapability bool

	// StatusSource is composed outside ui. The UI only submits display facts and
	// consumes semantic snapshots through one Bubble Tea listener.
	StatusSource customization.Source
	// LocalSessionContext optionally resolves the privileged local session root.
	// The root is used only as a direct status-command CWD, never UI state.
	LocalSessionContext client.LocalSessionContextGetter

	// ClientBuild is the local mecatui build identity and Embedded selects the
	// local server identity path for /diagnostics.
	ClientBuild string
	Embedded    bool

	// Display-only context for the header bar.
	Server         string
	ConnectionMode string
	Workspace      string
	Mode           string
	Model          string
	// ModeServerDefault asks the server to choose the first session's permission
	// mode: no --permission-mode or --mode was given, so the create
	// carries an unspecified mode and the server's configured default applies
	// (embedded: the operator's permissionMode: key; connect: the remote server's
	// own default). The created session's mode is read back with GetSession, so the
	// header never guesses it. Mode is then only the pre-session display fallback.
	ModeServerDefault bool
	// Resume is a statically validated existing chat selected before Bubble Tea
	// starts. Its authoritative transcript is adopted without CreateSession; nil
	// preserves the new-session default.
	Resume *client.ResumeSelection
	// BrowseSessions launches into the same inventory used by /sessions without
	// creating a throwaway session. New-chat creation remains gated on the startup
	// model-list reconcile.
	BrowseSessions bool
	// InitialPrompt is a CLI-supplied seed prompt auto-submitted once the first
	// session is ready (the equivalent of typing the prompt and pressing enter).
	// Empty = no seed. Cleared after the first use so a
	// /models restart or /clear never re-submits it. Populated by main.go from
	// -p/--prompt + --prompt-file.
	InitialPrompt string
	// DebugTarget is immutable launch metadata for a dedicated analysis session.
	// It is presentation/control state only; the client adapter owns wire projection.
	DebugTarget string
	// DebugMCP names the selected server-global reporting servers shown in the
	// debugger's privacy disclosure. It is presentation-only; authorization remains
	// server-owned.
	DebugMCP []string

	// Version is the mecatui build identity, shown on the first-run welcome splash
	// (e.g. "v0.3.1", "dev+0123456789ab", or "dev"). Threaded from the shared
	// internal/buildinfo.BuildID; "" omits the version line.
	// Display-only.
	Version string

	// NoBanner suppresses the rich first-run welcome splash (mascot + gradient
	// wordmark): the zero-state then renders the LEGACY plain card (title + prompt
	// hint + affordances). Set by --no-banner, --quiet, or a non-interactive stdin
	// (composed in main). Default false (full splash).
	NoBanner bool

	// StartupProgress carries bounded host-composition progress while the first
	// session is being created. StartupFailureHint returns matching host-owned
	// remediation when that preparation fails behind a redacted server error.
	StartupProgress    <-chan string
	StartupFailureHint func() string

	// Ctx is the program-level context; per-run stream contexts derive from it.
	Ctx context.Context //nolint:containedctx // stored to parent per-run stream cancels

	// AgentHook mirrors the session lifecycle to the host tool's AGENT LIFECYCLE
	// HOOK, in the cross-vendor hook schema Claude Code originated and Codex
	// adopted. nil when no supported host is detected — the ordinary standalone
	// run — so the reducer's nil check reflects real absence. Start fires on the
	// run's first turn, PermissionRequest on a MAIN (non-child) approval ask, and
	// Stop on the terminal result. See cmd/mecatui/agenthook.
	AgentHook LifecycleNotifier

	// NoAltScreen disables the alternate screen buffer, rendering inline in the
	// terminal's normal buffer. Default false (full-screen TUI on the alt screen).
	// Set true by the --no-alt-screen/--inline flag — a first-class user opt-out
	// for streaming the session into native scrollback (so it stays
	// searchable/scrollable after exit) — and by golden tests so the final frame
	// persists in the captured output instead of being cleared on exit.
	NoAltScreen bool

	// NoMouse disables mouse capture on the alt screen (View leaves MouseMode at
	// MouseModeNone), so the terminal's OWN click-drag selection works again — at
	// the cost of in-app mouse-wheel scroll and the in-app drag-select/copy layer
	// (selectable() returns false). Keyboard scroll is unaffected. Default false
	// (mouse captured). Set true by --no-mouse / MECATUI_NO_MOUSE=1. Inert under
	// NoAltScreen (mouse is already off inline). The escape hatch for terminals
	// that strip OSC52 or users who prefer native selection.
	NoMouse bool

	// TerminalTitle receives the display-safe snapshot during View. Its implementation
	// stages the title; Bubble Tea's configured output writer delivers it with the frame.
	TerminalTitle func(customization.Input)

	// Debug enables every client-side diagnostic surface. DebugMouse, DebugSteer,
	// and DebugAsk remain narrow compatibility aliases for their original surfaces.
	Debug bool

	// DebugMouse turns on a footer diagnostic overlay when Debug is false: on every
	// mouse press/motion the footer-left is overridden with raw coordinates and
	// their content mapping.
	DebugMouse bool

	// DebugSteer traces steer correlation in the status line when Debug is false.
	DebugSteer bool

	// DebugAsk registers /debug-ask when Debug is false. The command injects a fake
	// long-args permission ask through the real reducer.
	DebugAsk bool

	// KeyOverrides maps a keyMap field name (e.g. "Agents") to its replacement chord(s).
	// nil = no overrides, byte-identical to today. Resolved+validated in composition.
	KeyOverrides map[string][]string
	// contains filtered or unexported fields
}

type ExecutionCreator interface {
	CreateSessionWithExecution(ctx context.Context, sel client.ModelSelection, mode string, choice client.ExecutionChoice) (string, client.Capabilities, client.ResolvedModel, error)
}

type HitID uint64

type LearningSettings interface {
	Advance() (fromLabel, toLabel, restart string, err error)
	AdvanceSensitivity() (fromLabel, toLabel, restart string, err error)
}

type LifecycleNotifier interface {
	// Start signals the agent began work (the run's first turn).
	Start(ctx context.Context, sessionID string)
	// PermissionRequest signals the agent is blocked on a human approval. It
	// does not affect the run's busy state (a Stop must still follow).
	PermissionRequest(ctx context.Context, sessionID, message string)
	// PermissionResult signals that the human answered the approval and the same
	// run resumed working.
	PermissionResult(ctx context.Context, sessionID string)
	// Stop signals the run reached a terminal state; failed selects the error
	// terminal, message is an optional preview for the notification.
	Stop(ctx context.Context, sessionID string, failed bool, message string)
}

type Model struct {
	// contains filtered or unexported fields
}

type PendingApprovalController interface {
	WatchPendingApprovalRun(context.Context, client.PendingApproval) (PendingApprovalWatch, error)
	ResolvePendingApproval(context.Context, client.PendingApproval, client.Verdict) error
	CancelPendingRun(context.Context, client.PendingApproval) error
}

type PendingApprovalWatch interface {
	Recv() (client.PendingApprovalEvent, error)
	Close()
}

type PermissionModeEntry struct {
	Name        string
	Posture     string
	SessionMode string
}

type SelectionStore interface {
	Save(workspace string, sel client.ModelSelection) error
	SaveGlobalDefault(sel client.ModelSelection) error
}

type ServerInfoGetter interface {
	GetServerInfo(ctx context.Context, providerID string) (client.ServerInfo, error)
}

type SessionBoundConverser interface {
	OpenConverseForSession(ctx context.Context, sessionID string) (*client.Stream, error)
}

type SessionCreator interface {
	CreateSession(ctx context.Context, sel client.ModelSelection, mode string) (string, client.Capabilities, client.ResolvedModel, error)
	// CreateSessionWithCarryover forks the current transcript with optional model
	// overrides; placement and omitted settings are inherited by the server.
	CreateSessionWithCarryover(ctx context.Context, sourceSessionID string, sel client.ModelSelection) (string, client.Capabilities, client.ResolvedModel, error)
	// ClearSession creates an empty-history successor. selector is nil for ordinary
	// /clear and points only to an opaque ListWorktrees result for a worktree switch.
	ClearSession(ctx context.Context, sourceSessionID string, selector *client.WorktreeSelector) (string, client.SessionSnapshot, error)
	// CloseSession ends a server-side session by id. The /models restart-now handoff
	// closes the OLD session before creating the new one so a model switch leaves no
	// orphaned server-side session. Best-effort: the caller proceeds with the new
	// create even if the close errors.
	CloseSession(ctx context.Context, id string) error
	// GetSession re-reads the EFFECTIVE resolved model for an existing session. The
	// footer context-meter heal (issue #66) fires it on a turn boundary while the
	// meter's denominator is still unknown — the create-time echo can carry a 0 /
	// curated-floor window for a session on a LIVE-ONLY model whose async live
	// model-list swap had not yet landed, and the server's ResolvedModel resolves to
	// the real live window once it has. SessionCreator is the canonical ui-injection
	// seam for it (the method also satisfies the narrower client.SessionGetter that
	// RefreshResolvedModelCmd consumes); *client.Client (via the sessionAdapter) and
	// the test fakes satisfy both.
	GetSession(ctx context.Context, id string) (client.SessionSnapshot, error)
	// SetMode asks the server to change the current session's permission mode and
	// returns the server-confirmed mode. Mid-turn attempts may be rejected; the ui
	// defers and retries at the next prompt boundary.
	SetMode(ctx context.Context, id, mode string) (string, error)
	// ForkSession creates a peer session from srcID's conversation-history snapshot
	// with an OPTIONAL reasoning-effort override (empty
	// inherits the source's) and returns the new session id. The /effort fork-resume
	// handoff uses it: the transcript SURVIVES the effort switch because the fork
	// carries it (title is omitted — the fork inherits the source's title; provider
	// and model ALWAYS inherit). The caller owns closing the source session and the
	// GetSession refetch for the fork's resolved-model echo.
	ForkSession(ctx context.Context, srcID, reasoningEffort string) (string, error)
}