controller.go

// Package controller is the reusable host API for a controller board.
//
// It owns authenticated serial discovery, the native framed protocol, live
// status, settings, learned RF records, and the same command engine used by the
// CLI and TUI. Applications can embed this package without starting a terminal
// UI or a subprocess.
package controller

import (
	"context"
	"crypto/rand"
	"encoding/hex"
	"encoding/json"
	"errors"
	"fmt"
	"io"
	"sort"
	"strconv"
	"strings"
	"sync"
	"time"

	"pccontroller.local/controller/internal/appconfig"
	"pccontroller.local/controller/internal/control"
	"pccontroller.local/controller/internal/discovery"
	"pccontroller.local/controller/internal/hostos"
	"pccontroller.local/controller/internal/link"
	"pccontroller.local/controller/internal/native"
	"pccontroller.local/controller/internal/ports"
	"pccontroller.local/controller/internal/programmer"
	"pccontroller.local/controller/internal/shell"
)

// Protocol, configuration, and host-service aliases form the embeddable API's
// shared data model without duplicating their wire or validation definitions.
type (
	Hello                     = native.Hello
	Status                    = native.Status
	Settings                  = native.Settings
	BoardName                 = native.BoardName
	RFEntry                   = native.RFEntry
	BoardAutomationRecord     = native.AutomationRecord
	BoardAutomationReadback   = native.AutomationRecordReadback
	BoardAutomationSnapshot   = control.BoardAutomationSnapshot
	OfflineEEPROMDecode       = programmer.OfflineEEPROMDecode
	OfflineAutomationDecode   = programmer.OfflineAutomationDecode
	OfflineAutomationBank     = programmer.OfflineAutomationBank
	OfflineAutomationRecord   = programmer.OfflineAutomationRecord
	RFConfig                  = appconfig.RFConfig
	RFCategory                = appconfig.RFCategory
	RFCodeKey                 = appconfig.RFCodeKey
	RFMetadata                = appconfig.RFMetadata
	TemperatureSensor         = native.TemperatureSensor
	DeviceEvent               = native.DeviceEvent
	PWMValues                 = native.PWMValues
	FrontPanel                = native.FrontPanel
	Melody                    = appconfig.Melody
	MelodyNote                = appconfig.MelodyNote
	StatusLEDEffect           = appconfig.StatusLEDEffect
	StatusLEDState            = native.StatusLEDState
	StatusProfile             = native.StatusProfile
	StatusEffectOptions       = native.StatusEffectOptions
	StatusLEDPolicy           = appconfig.StatusLEDPolicy
	StatusLEDVisual           = appconfig.StatusLEDVisual
	RGBColor                  = appconfig.RGBColor
	MotionSideState           = control.MotionSideState
	MotionSnapshot            = control.MotionSnapshot
	OutputStreamState         = control.OutputStreamState
	StatusSample              = control.StatusSample
	TimelineEntry             = control.TimelineEntry
	HardwareProblem           = ports.HardwareProblem
	HistoryOptions            = control.HistoryOptions
	RFLearnMode               = control.RFLearnMode
	RFLearnOptions            = control.RFLearnOptions
	RFLearnState              = control.RFLearnState
	MenuPageInfo              = control.MenuPageInfo
	MenuCatalog               = control.MenuCatalog
	MenuLayout                = control.MenuLayout
	HostMenuDirectory         = native.HostMenuDirectory
	HostMenuDirectoryEntry    = native.HostMenuDirectoryEntry
	HostMenuContent           = native.HostMenuContent
	HostMenuState             = native.HostMenuState
	HostMenuContentRequest    = native.HostMenuContentRequest
	I2CTransferResult         = native.I2CTransferResult
	LCDPresentationOptions    = control.LCDPresentationOptions
	LCDPresentationState      = control.LCDPresentationState
	DisplayRepeat             = control.DisplayRepeat
	DisplayRequest            = control.DisplayRequest
	DisplayResult             = control.DisplayResult
	OSPolicy                  = hostos.Policy
	VirtualKeyPolicy          = hostos.VirtualKeyPolicy
	PowerPolicy               = hostos.PowerPolicy
	VirtualKeyRequest         = hostos.VirtualKeyRequest
	PowerRequest              = hostos.PowerRequest
	OSActionResult            = hostos.ActionResult
	SystemStatus              = hostos.SystemStatus
	CommandDescriptor         = shell.CommandDescriptor
	ToolchainSyncOptions      = programmer.ToolchainSyncOptions
	ToolchainSyncStep         = programmer.ToolchainSyncStep
	ToolchainSyncReport       = programmer.ToolchainSyncReport
	ToolchainProfile          = programmer.ToolchainProfile
	ToolchainPolicy           = programmer.ToolchainPolicy
	ToolchainLock             = programmer.ToolchainLock
	ToolchainCanary           = programmer.ToolchainCanary
	ToolchainResolution       = programmer.ToolchainResolution
	ToolchainChange           = programmer.ToolchainChange
	ToolchainResolveOptions   = programmer.ToolchainResolveOptions
	ToolchainBootstrapOptions = programmer.ToolchainBootstrapOptions
	ToolchainBootstrapReport  = programmer.ToolchainBootstrapReport
	ProgramMode               = control.ProgramMode
	ProgramStateOwner         = control.ProgramStateOwner
	ProgramStateSnapshot      = control.ProgramStateSnapshot
	ProgramStateLease         = control.ProgramStateLease
	EmergencyStopState        = control.EmergencyStopState
	PortProcessSnapshot       = control.PortProcessSnapshot
	DiscoveryInstance         = discovery.Instance
	DiscoveryOptions          = discovery.Options
)

// RF learning modes select indefinite multi-code or bounded timer operation.
const (
	RFLearnIndefinite = control.RFLearnIndefinite
	RFLearnTimer      = control.RFLearnTimer
)

const (
	DisplayRepeatOnce     = control.DisplayRepeatOnce
	DisplayRepeatLoop     = control.DisplayRepeatLoop
	DisplayRepeatInterval = control.DisplayRepeatInterval
)

// ParseRFLearnMode accepts the canonical RF learning mode and documented aliases.
func ParseRFLearnMode(value string) (RFLearnMode, error) {
	return control.ParseRFLearnMode(value)
}

// RFAction identifies the peripheral domain invoked by a learned RF code.
type RFAction byte

// RFBehavior selects press, toggle, momentary, or motion behavior.
type RFBehavior byte

// RelayMotion selects the requested state of one interlocked motion side.
type RelayMotion byte

// RF mapping, motion, settings, and program-state constants mirror the native API.
const (
	RFActionNone  RFAction = RFAction(native.RFActionNone)
	RFActionKey   RFAction = RFAction(native.RFActionKey)
	RFActionMenu  RFAction = RFAction(native.RFActionMenu)
	RFActionRelay RFAction = RFAction(native.RFActionRelay)
	RFActionSide  RFAction = RFAction(native.RFActionSide)
	RFActionPWM   RFAction = RFAction(native.RFActionPWM)

	RFBehaviorPress     RFBehavior = RFBehavior(native.RFBehaviorPress)
	RFBehaviorToggle    RFBehavior = RFBehavior(native.RFBehaviorToggle)
	RFBehaviorMomentary RFBehavior = RFBehavior(native.RFBehaviorMomentary)
	RFBehaviorUp        RFBehavior = RFBehavior(native.RFBehaviorUp)
	RFBehaviorDown      RFBehavior = RFBehavior(native.RFBehaviorDown)
	RFBehaviorStop      RFBehavior = RFBehavior(native.RFBehaviorStop)

	RelayMotionStop RelayMotion = 0
	RelayMotionUp   RelayMotion = 1
	RelayMotionDown RelayMotion = 2

	SettingsSaveLastPage            byte = native.SettingsSaveLastPage
	SettingsStatusColorMask         byte = native.SettingsStatusColorMask
	SettingsVoltageDecimalMask      byte = native.SettingsVoltageDecimalMask
	SettingsCurrentDecimalMask      byte = native.SettingsCurrentDecimalMask
	SettingsDefaultDecimals         byte = native.SettingsDefaultDecimals
	MotionDoorAlways                byte = native.MotionDoorAlways
	MotionDoorClosedOnly            byte = native.MotionDoorClosedOnly
	MotionDoorOpenOnly              byte = native.MotionDoorOpenOnly
	MotionDoorNever                 byte = native.MotionDoorNever
	ProgramIdle                          = control.ProgramIdle
	ProgramRunning                       = control.ProgramRunning
	BoardAutomationAllocateID            = native.AutomationAllocateID
	BoardAutomationEnabled               = native.AutomationEnabled
	BoardAutomationEventDoor             = native.AutomationEventDoor
	BoardAutomationEventBluetooth        = native.AutomationEventBluetooth
	BoardAutomationEventHost             = native.AutomationEventHost
	BoardAutomationEventRelay            = native.AutomationEventRelay
	BoardAutomationEventLearnedRF        = native.AutomationEventLearnedRF
	BoardAutomationEventKey              = native.AutomationEventKey
	BoardAutomationEventAlert            = native.AutomationEventAlert
	BoardAutomationEventBoot             = native.AutomationEventBoot
	BoardAutomationActionSafeStop        = native.AutomationActionSafeStop
	BoardAutomationActionMotionStop      = native.AutomationActionMotionStop
	BoardAutomationActionRelay           = native.AutomationActionRelay
	BoardAutomationActionPWM             = native.AutomationActionPWM
	BoardAutomationActionStatusCue       = native.AutomationActionStatusCue
	BoardAutomationActionBuzzer          = native.AutomationActionBuzzer
	BoardAutomationActionRFTransmit      = native.AutomationActionRFTransmit
	BoardAutomationActionHostMacro       = native.AutomationActionHostMacroRequest
)

// ValidateBoardAutomation applies the same bounded safety contract as the
// firmware without contacting a board.
func ValidateBoardAutomation(record BoardAutomationRecord) error {
	return native.ValidateAutomationRecord(record)
}

// DecodeOfflineEEPROMHex performs read-only forensic decoding of settings,
// learned RF, reset history, and an optional automation-profile tail.
func DecodeOfflineEEPROMHex(path string) (OfflineEEPROMDecode, error) {
	return programmer.DecodeOfflineEEPROMHex(path)
}

// RFMapping binds a learned record to one board action and behavior.
type RFMapping struct {
	Action   RFAction   `json:"action"`
	Value    byte       `json:"value"`
	Behavior RFBehavior `json:"behavior"`
}

// OutputOperation tracks an asynchronous melody or status-LED effect.
type OutputOperation struct {
	ID   uint64       `json:"id"`
	Kind string       `json:"kind"`
	Name string       `json:"name"`
	Done <-chan error `json:"-"`
}

// StatusUpdate contains one subscribed telemetry result or its polling error.
type StatusUpdate struct {
	HostInstanceID       string    `json:"host_instance_id,omitempty"`
	ConnectionGeneration uint64    `json:"connection_generation"`
	BoardConnected       bool      `json:"board_connected"`
	HaveStatus           bool      `json:"have_status"`
	Time                 time.Time `json:"time"`
	Status               Status    `json:"status"`
	Error                string    `json:"error,omitempty"`
}

func (client *Client) CachedStatusObservation() StatusUpdate {
	status, have, stamp, generation, connected := client.runtime.ObservedStatus()
	return StatusUpdate{Status: status, HaveStatus: have, Time: stamp, ConnectionGeneration: generation, BoardConnected: connected}
}

// Options configures discovery, transport, tooling, automation, and host policy.
type Options struct {
	Port                  string                 `json:"port,omitempty"`
	VID                   string                 `json:"vid,omitempty"`
	PID                   string                 `json:"pid,omitempty"`
	Name                  string                 `json:"name,omitempty"`
	PreferredDevice       *PortInfo              `json:"preferred_device,omitempty"`
	BaudRate              int                    `json:"baud_rate,omitempty"`
	StartupWait           time.Duration          `json:"startup_wait,omitempty"`
	RequestTimeout        time.Duration          `json:"request_timeout,omitempty"`
	HelloAttempts         int                    `json:"hello_attempts,omitempty"`
	ResetOnReconnect      bool                   `json:"reset_on_reconnect,omitempty"`
	ReconnectInitialDelay time.Duration          `json:"reconnect_initial_delay,omitempty"`
	ReconnectMaximumDelay time.Duration          `json:"reconnect_maximum_delay,omitempty"`
	ProjectPath           string                 `json:"project_path,omitempty"`
	FQBN                  string                 `json:"fqbn,omitempty"`
	FirmwareFeatures      []string               `json:"firmware_features,omitempty"`
	ToolchainCLI          string                 `json:"toolchain_cli,omitempty"`
	ToolchainConfig       string                 `json:"toolchain_config,omitempty"`
	Avrdude               string                 `json:"avrdude,omitempty"`
	AvrdudeConf           string                 `json:"avrdude_conf,omitempty"`
	AvrdudeBackend        string                 `json:"avrdude_backend,omitempty"`
	AvrdudeAdapter        string                 `json:"avrdude_adapter,omitempty"`
	Programmer            string                 `json:"programmer,omitempty"`
	Macros                []Macro                `json:"macros,omitempty"`
	StripEffects          []StripEffect          `json:"strip_effects,omitempty"`
	Melodies              []Melody               `json:"melodies,omitempty"`
	StatusEffects         []StatusLEDEffect      `json:"status_effects,omitempty"`
	Scripts               map[string]string      `json:"scripts,omitempty"`
	Automations           []Automation           `json:"automations,omitempty"`
	MotionDoorPolicy      string                 `json:"motion_door_policy,omitempty"`
	LCDPresentation       LCDPresentationOptions `json:"lcd_presentation,omitempty"`
	RF                    RFConfig               `json:"rf"`
	OSActions             OSPolicy               `json:"os_actions"`
}

// Macro describes a host-owned sequence of peripheral operations. Mode chooses
// host-clocked alpha playback or the stricter MCU timing engine.
type Macro struct {
	ID                  byte        `json:"id"`
	Name                string      `json:"name"`
	Mode                string      `json:"mode,omitempty"`
	Category            string      `json:"category,omitempty"`
	Color               string      `json:"color,omitempty"`
	Label               string      `json:"label,omitempty"`
	LCDMessage          string      `json:"lcd_message,omitempty"`
	TimingToleranceUS   uint32      `json:"timing_tolerance_us,omitempty"`
	KeepOutputsOnCancel bool        `json:"keep_outputs_on_cancel,omitempty"`
	BoardProfileKey     string      `json:"board_profile_key,omitempty"`
	BoardProfileMode    string      `json:"board_profile_mode,omitempty"`
	Steps               []MacroStep `json:"steps"`
	RepeatCount         *uint16     `json:"repeat_count,omitempty"`
	RepeatIntervalMS    uint32      `json:"repeat_interval_ms,omitempty"`
}

// MacroStep describes one timestamped operation within a Macro.
type MacroStep struct {
	AtUS         uint32   `json:"at_us,omitempty"`
	Kind         string   `json:"kind"`
	Target       byte     `json:"target,omitempty"`
	Value        uint16   `json:"value,omitempty"`
	DurationMS   uint16   `json:"duration_ms,omitempty"`
	ToValue      *uint16  `json:"to_value,omitempty"`
	Easing       string   `json:"easing,omitempty"`
	SampleRateHz byte     `json:"sample_rate_hz,omitempty"`
	FrequencyHz  uint16   `json:"frequency_hz,omitempty"`
	Text         string   `json:"text,omitempty"`
	Destination  string   `json:"destination,omitempty"`
	Code         uint32   `json:"code,omitempty"`
	Bits         byte     `json:"bits,omitempty"`
	Protocol     byte     `json:"protocol,omitempty"`
	PulseUS      uint16   `json:"pulse_us,omitempty"`
	Red          byte     `json:"red,omitempty"`
	Green        byte     `json:"green,omitempty"`
	Blue         byte     `json:"blue,omitempty"`
	Brightness   byte     `json:"brightness,omitempty"`
	ToRed        *byte    `json:"to_red,omitempty"`
	ToGreen      *byte    `json:"to_green,omitempty"`
	ToBlue       *byte    `json:"to_blue,omitempty"`
	ToBrightness *byte    `json:"to_brightness,omitempty"`
	Opcode       byte     `json:"opcode,omitempty"`
	PayloadHex   string   `json:"payload_hex,omitempty"`
	ActionIDs    []string `json:"action_ids,omitempty"`
}

// StripEffect is a PCController-owned, user-editable declarative light program.
type StripEffect struct {
	ID                string       `json:"id"`
	Name              string       `json:"name"`
	Category          string       `json:"category,omitempty"`
	Description       string       `json:"description,omitempty"`
	Program           StripProgram `json:"program"`
	DefaultFPS        int          `json:"default_fps"`
	DefaultDurationMS int          `json:"default_duration_ms"`
	DefaultPixels     int          `json:"default_pixels,omitempty"`
}

type StripColor struct {
	Red   byte `json:"red"`
	Green byte `json:"green"`
	Blue  byte `json:"blue"`
}

type StripEnvelopePoint struct {
	AtMS      int  `json:"at_ms"`
	Intensity byte `json:"intensity"`
}

type StripProgram struct {
	Primitive      string               `json:"primitive"`
	Primary        StripColor           `json:"primary"`
	Secondary      StripColor           `json:"secondary,omitempty"`
	PeriodMS       int                  `json:"period_ms"`
	StepMS         int                  `json:"step_ms,omitempty"`
	SwapAfterSteps int                  `json:"swap_after_steps,omitempty"`
	DimIntensity   byte                 `json:"dim_intensity,omitempty"`
	TailPixels     int                  `json:"tail_pixels,omitempty"`
	Envelope       []StripEnvelopePoint `json:"envelope,omitempty"`
}

// Automation maps an event match to one or more host-side actions.
type Automation struct {
	Name       string             `json:"name"`
	Enabled    bool               `json:"enabled"`
	CooldownMS int                `json:"cooldown_ms,omitempty"`
	Match      AutomationMatch    `json:"match"`
	Actions    []AutomationAction `json:"actions"`
}

// AutomationMatch selects the event properties that trigger an automation.
type AutomationMatch struct {
	Kind       string  `json:"kind"`
	Lifecycle  string  `json:"lifecycle,omitempty"`
	State      string  `json:"state,omitempty"`
	Contains   string  `json:"contains,omitempty"`
	Key        byte    `json:"key,omitempty"`
	Gesture    string  `json:"gesture,omitempty"`
	Source     string  `json:"source,omitempty"`
	RFID       *byte   `json:"rf_id,omitempty"`
	RFCode     *uint32 `json:"rf_code,omitempty"`
	RFProtocol byte    `json:"rf_protocol,omitempty"`
	RFBits     byte    `json:"rf_bits,omitempty"`
}

// AutomationAction describes one command, macro, integration, or OS action.
type AutomationAction struct {
	Type       string      `json:"type"`
	Command    string      `json:"command,omitempty"`
	Macro      string      `json:"macro,omitempty"`
	Executable string      `json:"executable,omitempty"`
	Detached   bool        `json:"detached,omitempty"`
	Args       []string    `json:"args,omitempty"`
	Script     string      `json:"script,omitempty"`
	Event      string      `json:"event,omitempty"`
	RF         *RFTransmit `json:"rf,omitempty"`
	VirtualKey string      `json:"virtual_key,omitempty"`
	HoldMS     int         `json:"hold_ms,omitempty"`
	Power      string      `json:"power,omitempty"`
	Confirm    string      `json:"confirm,omitempty"`
	AppKind    string      `json:"app_kind,omitempty"`
	AppValue   string      `json:"app_value,omitempty"`
	AppTarget  string      `json:"app_target,omitempty"`
	ActionID   string      `json:"action_id,omitempty"`
}

// RFTransmit contains the complete waveform metadata for one 433 MHz send action.
type RFTransmit struct {
	Code     uint32 `json:"code"`
	Bits     byte   `json:"bits"`
	Protocol byte   `json:"protocol"`
	PulseUS  uint16 `json:"pulse_us,omitempty"`
	Repeats  byte   `json:"repeats,omitempty"`
}

// RFEntryView combines one MCU record with host-owned display metadata.
type RFEntryView struct {
	ID          byte   `json:"id"`
	Code        uint32 `json:"code"`
	CodeDisplay string `json:"code_display"`
	Bits        byte   `json:"bits"`
	Protocol    byte   `json:"protocol"`
	PulseUS     uint16 `json:"pulse_us"`
	ActionKind  byte   `json:"action_kind"`
	ActionValue byte   `json:"action_value"`
	Behavior    byte   `json:"behavior"`
	Name        string `json:"name,omitempty"`
	Category    string `json:"category,omitempty"`
}

// PortInfo identifies one serial candidate with stable USB metadata when available.
type PortInfo struct {
	Name         string `json:"name"`
	DisplayName  string `json:"display_name,omitempty"`
	VID          string `json:"vid,omitempty"`
	PID          string `json:"pid,omitempty"`
	Product      string `json:"product,omitempty"`
	Manufacturer string `json:"manufacturer,omitempty"`
	SerialNumber string `json:"serial_number,omitempty"`
	FriendlyName string `json:"friendly_name,omitempty"`
	InstanceID   string `json:"instance_id,omitempty"`
}

// IlluminationState combines the persisted enclosure-light policy with the
// authoritative PWM value currently applied to the dedicated channel. Values
// ending in Brightness use the board's 0..255 settings scale; PWM values use
// the PCA controller's native logical 0..4095 scale.
type IlluminationState struct {
	Available         bool      `json:"available"`
	Mode              byte      `json:"mode"`
	OnBrightness      byte      `json:"on_brightness"`
	OffBrightness     byte      `json:"off_brightness"`
	DoorOpen          bool      `json:"door_open"`
	TargetBrightness  byte      `json:"target_brightness"`
	TargetPWM         uint16    `json:"target_pwm"`
	AppliedBrightness byte      `json:"applied_brightness"`
	AppliedPWM        uint16    `json:"applied_pwm"`
	AtTarget          bool      `json:"at_target"`
	Persisted         bool      `json:"persisted"`
	UpdatedAt         time.Time `json:"updated_at,omitempty"`
}

// Snapshot is a point-in-time view of connection, board, and front-panel state.
type Snapshot struct {
	HostInstanceID           string                          `json:"host_instance_id,omitempty"`
	Connected                bool                            `json:"connected"`
	Paused                   bool                            `json:"paused"`
	Port                     PortInfo                        `json:"port"`
	Hello                    Hello                           `json:"hello"`
	BoardName                BoardName                       `json:"board_name"`
	HaveBoardName            bool                            `json:"have_board_name"`
	Status                   Status                          `json:"status"`
	Settings                 Settings                        `json:"settings"`
	HaveStatus               bool                            `json:"have_status"`
	HaveSettings             bool                            `json:"have_settings"`
	StatusUpdated            time.Time                       `json:"status_updated,omitempty"`
	ConnectionState          string                          `json:"connection_state"`
	ConnectionReason         string                          `json:"connection_reason,omitempty"`
	ConnectionUpdated        time.Time                       `json:"connection_updated,omitempty"`
	ConnectionPhase          string                          `json:"connection_phase"`
	ConnectionAttempt        uint64                          `json:"connection_attempt,omitempty"`
	ConnectionGeneration     uint64                          `json:"connection_generation,omitempty"`
	ConnectionAttemptStarted time.Time                       `json:"connection_attempt_started,omitempty"`
	ConnectionNextRetry      time.Time                       `json:"connection_next_retry,omitempty"`
	ConnectionRetryDelayMS   int64                           `json:"connection_retry_delay_ms,omitempty"`
	ConnectionCandidate      PortInfo                        `json:"connection_candidate"`
	ResetLinesAvailable      bool                            `json:"reset_lines_available"`
	ResetLinesPort           PortInfo                        `json:"reset_lines_port"`
	ResetLinesReason         string                          `json:"reset_lines_reason,omitempty"`
	ProgramState             ProgramStateSnapshot            `json:"program_state"`
	Programming              control.ProgrammingSnapshot     `json:"programming"`
	EmergencyStop            EmergencyStopState              `json:"emergency_stop"`
	RFLearning               RFLearnState                    `json:"rf_learning"`
	Macros                   control.MacroSnapshot           `json:"macros"`
	Effects                  []control.EffectDescriptor      `json:"effects"`
	EffectGroups             []control.EffectGroupDescriptor `json:"effect_groups"`
	HardwareProblems         []HardwareProblem               `json:"hardware_problems,omitempty"`
	FrontPanel               FrontPanel                      `json:"front_panel"`
	HaveFrontPanel           bool                            `json:"have_front_panel"`
	HaveFrontPanelSegments   bool                            `json:"have_front_panel_segments"`
	FrontPanelUpdated        time.Time                       `json:"front_panel_updated,omitempty"`
	StatusLED                StatusLEDState                  `json:"status_led"`
	HaveStatusLED            bool                            `json:"have_status_led"`
	StatusLEDUpdated         time.Time                       `json:"status_led_updated,omitempty"`
	StatusLEDRevision        uint64                          `json:"status_led_revision,omitempty"`
	PWMValues                *PWMValues                      `json:"pwm_values,omitempty"`
	PWMRevision              uint64                          `json:"pwm_revision,omitempty"`
	PWMUpdated               time.Time                       `json:"pwm_updated,omitempty"`
	PWMRecall                [16]control.PWMRecallValue      `json:"pwm_recall"`
	Motion                   MotionSnapshot                  `json:"motion"`
	Outputs                  OutputStreamState               `json:"outputs"`
	StripEffects             []control.StripEffectDescriptor `json:"strip_effects,omitempty"`
	Illumination             IlluminationState               `json:"illumination"`
	PortProcess              PortProcessSnapshot             `json:"port_process"`
}

// Unknown offline settings are not an EEPROM write payload. Decode their
// presence flag first so an initial pushed offline snapshot remains usable.
func (snapshot *Snapshot) UnmarshalJSON(data []byte) error {
	type fields Snapshot
	var result Snapshot
	wire := struct {
		*fields
		Settings json.RawMessage `json:"settings"`
	}{fields: (*fields)(&result)}
	if err := json.Unmarshal(data, &wire); err != nil {
		return err
	}
	if result.HaveSettings {
		if err := json.Unmarshal(wire.Settings, &result.Settings); err != nil {
			return err
		}
	}
	*snapshot = result
	return nil
}

// Event is the normalized event envelope shared by embedders and bridge clients.
type Event struct {
	ID          uint64                       `json:"id"`
	Time        time.Time                    `json:"time"`
	Kind        string                       `json:"kind"`
	Stream      string                       `json:"stream"`
	Text        string                       `json:"text"`
	Opcode      byte                         `json:"opcode,omitempty"`
	Seq         byte                         `json:"seq,omitempty"`
	Payload     []byte                       `json:"payload,omitempty"`
	Device      *DeviceEvent                 `json:"device,omitempty"`
	Lifecycle   string                       `json:"lifecycle,omitempty"`
	Port        PortInfo                     `json:"port,omitempty"`
	Reason      string                       `json:"reason,omitempty"`
	State       string                       `json:"state,omitempty"`
	Key         byte                         `json:"key,omitempty"`
	Gesture     string                       `json:"gesture,omitempty"`
	Source      string                       `json:"source,omitempty"`
	Target      string                       `json:"target,omitempty"`
	Targets     []string                     `json:"targets,omitempty"`
	MessageType string                       `json:"message_type,omitempty"`
	Action      string                       `json:"action,omitempty"`
	Severity    string                       `json:"severity,omitempty"`
	Correlation string                       `json:"correlation,omitempty"`
	Delivery    string                       `json:"delivery,omitempty"`
	Metadata    map[string]string            `json:"metadata,omitempty"`
	Programming *control.ProgrammingSnapshot `json:"programming,omitempty"`
	SourceID    *byte                        `json:"source_id,omitempty"`
	RFID        *byte                        `json:"rf_id,omitempty"`
	RFCode      uint32                       `json:"rf_code,omitempty"`
	RFBits      byte                         `json:"rf_bits,omitempty"`
	RFProtocol  byte                         `json:"rf_protocol,omitempty"`
	RFPulseUS   uint16                       `json:"rf_pulse_us,omitempty"`
	ResetCause  byte                         `json:"reset_cause,omitempty"`
	ResetCount  uint32                       `json:"reset_count,omitempty"`
}

// FirmwareBuildRequest is the strict, typed alternative to sending a raw
// shell command to a remote host. An empty request uses the host's configured
// firmware feature profile.
type FirmwareBuildRequest struct {
	FirmwareFeatures   []string `json:"firmware_features,omitempty"`
	NoFirmwareFeatures bool     `json:"no_firmware_features,omitempty"`
}

// FirmwareBuildResult correlates the final normalized log with the ordered
// program.* events that WebSocket, Socket.IO, TUI, and long-poll clients see.
type FirmwareBuildResult struct {
	OperationID string `json:"operation_id"`
	Output      string `json:"output"`
}

// OpcodeFrame is the raw, versionless UART exchange result. Payload is kept
// opaque so clients can query firmware additions before the host understands
// their schema.
type OpcodeFrame struct {
	Opcode     byte   `json:"opcode"`
	Name       string `json:"name"`
	Sequence   byte   `json:"sequence"`
	Payload    []byte `json:"payload,omitempty"`
	PayloadHex string `json:"payload_hex,omitempty"`
}

// TextMessage is a typed envelope shared by IPC, WebSocket, webhooks, the host
// bridge, and LCD presentation. Action is descriptive; it is never executed
// implicitly. Remote command execution uses the authenticated execute method.
type TextMessage struct {
	Source      string            `json:"source"`
	Targets     []string          `json:"targets"`
	Type        string            `json:"type"`
	Text        string            `json:"text"`
	Line1       string            `json:"line1,omitempty"`
	Line2       string            `json:"line2,omitempty"`
	Action      string            `json:"action,omitempty"`
	Severity    string            `json:"severity,omitempty"`
	Correlation string            `json:"correlation,omitempty"`
	Delivery    string            `json:"delivery,omitempty"`
	Metadata    map[string]string `json:"metadata,omitempty"`
}

// Client owns one controller runtime, command engine, and host integration state.
type Client struct {
	runtime            *control.Runtime
	runtimeClose       func() error
	shutdownMu         sync.Mutex
	engine             *shell.Engine
	engineMu           sync.Mutex
	optionsMu          sync.RWMutex
	commandOptions     control.CommandOptions
	macroMu            sync.RWMutex
	macros             []appconfig.Macro
	outputMu           sync.RWMutex
	melodies           []appconfig.Melody
	statusEffects      []appconfig.StatusLEDEffect
	stripEffects       []appconfig.StripEffect
	outputs            *control.OutputScheduler
	hostMu             sync.RWMutex
	scripts            map[string]string
	automations        []appconfig.Automation
	safety             appconfig.Safety
	rfConfig           appconfig.RFConfig
	osPolicy           hostos.Policy
	events             chan Event
	done               chan struct{}
	doneOnce           sync.Once
	statusHub          statusSubscriptionHub
	statusFetch        func(context.Context) (Status, error)
	illuminationMu     sync.RWMutex
	illumination       IlluminationState
	illuminationPollAt time.Time
}

type statusSubscriber struct {
	interval time.Duration
	next     time.Time
	updates  chan StatusUpdate
}

type statusSubscriptionHub struct {
	mu          sync.Mutex
	subscribers map[uint64]*statusSubscriber
	nextID      uint64
	wake        chan struct{}
	running     bool
}

// New creates a client that owns its serial and background-service lifecycle.
func New(options Options) *Client {
	baud := options.BaudRate
	if baud == 0 {
		baud = link.DefaultBaudRate
	}
	fqbn := options.FQBN
	if fqbn == "" {
		fqbn = programmer.DefaultFQBN()
	}
	firmwareFeatures, firmwareFeaturesErr := programmer.NormalizeFirmwareFeatures(
		options.FirmwareFeatures,
	)
	runtime := control.New(control.Options{
		Filter: ports.Filter{
			Port:      options.Port,
			VID:       options.VID,
			PID:       options.PID,
			Name:      options.Name,
			Preferred: internalPortIdentity(options.PreferredDevice),
		},
		BaudRate:              baud,
		StartupWait:           options.StartupWait,
		RequestTimeout:        options.RequestTimeout,
		HelloAttempts:         options.HelloAttempts,
		ResetOnReconnect:      options.ResetOnReconnect,
		ReconnectInitialDelay: options.ReconnectInitialDelay,
		ReconnectMaximumDelay: options.ReconnectMaximumDelay,
	})
	client := &Client{
		runtime:      runtime,
		runtimeClose: runtime.Close,
		macros:       toAppMacros(options.Macros),
		melodies:     cloneMelodies(options.Melodies),
		statusEffects: append(
			[]appconfig.StatusLEDEffect(nil),
			options.StatusEffects...,
		),
		stripEffects: toAppStripEffects(options.StripEffects),
		scripts:      cloneStringMap(options.Scripts),
		automations:  toAppAutomations(options.Automations),
		safety: appconfig.Safety{
			MotionDoorPolicy: normalizedMotionDoorPolicy(options.MotionDoorPolicy),
		},
		rfConfig: cloneRFConfigOrDefault(options.RF),
		osPolicy: cloneOSPolicyOrDefault(options.OSActions),
		events:   make(chan Event, 256),
		done:     make(chan struct{}),
	}
	client.outputs = control.NewOutputScheduler(runtime)
	_ = runtime.LCDPresenter().Configure(options.LCDPresentation)
	client.commandOptions = control.CommandOptions{
		ProjectPath:           options.ProjectPath,
		FQBN:                  fqbn,
		FirmwareFeatures:      firmwareFeatures,
		FirmwareFeaturesError: firmwareFeaturesErr,
		ArduinoCLI:            options.ToolchainCLI,
		ArduinoConfig:         options.ToolchainConfig,
		Avrdude:               options.Avrdude,
		AvrdudeConf:           options.AvrdudeConf,
		AvrdudeBackend:        options.AvrdudeBackend, AvrdudeAdapter: options.AvrdudeAdapter,
		Programmer:       options.Programmer,
		HostConfig:       client.currentHostConfig,
		UpdateHostConfig: client.updateHostConfig,
		Outputs:          client.outputs,
	}
	client.engine = control.NewCommandEngine(runtime, control.CommandOptions{
		ProjectPath:           options.ProjectPath,
		FQBN:                  fqbn,
		FirmwareFeatures:      firmwareFeatures,
		FirmwareFeaturesError: firmwareFeaturesErr,
		Macros:                client.currentMacros,
		ArduinoCLI:            options.ToolchainCLI,
		ArduinoConfig:         options.ToolchainConfig,
		Avrdude:               options.Avrdude,
		AvrdudeConf:           options.AvrdudeConf,
		AvrdudeBackend:        options.AvrdudeBackend, AvrdudeAdapter: options.AvrdudeAdapter,
		Programmer:       options.Programmer,
		HostConfig:       client.currentHostConfig,
		UpdateHostConfig: client.updateHostConfig,
		Resolve:          client.currentCommandOptions,
		Outputs:          client.outputs,
	})
	automationContext, cancelAutomations := context.WithCancel(context.Background())
	go func() {
		<-client.done
		cancelAutomations()
	}()
	go control.RunAutomations(
		automationContext,
		runtime,
		client.engine,
		client.currentHostConfig,
	)
	go client.forwardEvents()
	return client
}

// AttachSharedRuntime creates an API/IPC facade around a runtime and command
// engine that are already owned by the current process. It lets an interactive
// TUI or shell be the one and only serial owner while secondary processes use
// JSON-RPC. The caller remains responsible for closing the runtime.
//
// This constructor is intended for sibling packages in this module. External
// embedders should normally use New, which owns its complete lifecycle.
func AttachSharedRuntime(
	runtime *control.Runtime,
	engine *shell.Engine,
) *Client {
	if runtime == nil {
		panic("controller: shared runtime is nil")
	}
	if engine == nil {
		panic("controller: shared command engine is nil")
	}
	return &Client{
		runtime:      runtime,
		runtimeClose: runtime.Close,
		engine:       engine,
		outputs:      runtime.EnsureOutputScheduler(),
		events:       make(chan Event),
		done:         make(chan struct{}),
	}
}

// ApplyHostOptions atomically refreshes runtime and host-owned configuration.
func (client *Client) ApplyHostOptions(options Options) bool {
	baud := options.BaudRate
	if baud == 0 {
		baud = link.DefaultBaudRate
	}
	changed := client.runtime.ApplyOptions(control.Options{
		Filter: ports.Filter{
			Port:      options.Port,
			VID:       options.VID,
			PID:       options.PID,
			Name:      options.Name,
			Preferred: internalPortIdentity(options.PreferredDevice),
		},
		BaudRate: baud, StartupWait: options.StartupWait,
		RequestTimeout:        options.RequestTimeout,
		HelloAttempts:         options.HelloAttempts,
		ResetOnReconnect:      options.ResetOnReconnect,
		ReconnectInitialDelay: options.ReconnectInitialDelay,
		ReconnectMaximumDelay: options.ReconnectMaximumDelay,
	})
	client.SetMacros(options.Macros)
	client.SetOutputDefinitions(options.Melodies, options.StatusEffects)
	_ = client.ConfigureLCDPresentation(options.LCDPresentation)
	client.hostMu.Lock()
	client.scripts = cloneStringMap(options.Scripts)
	client.automations = toAppAutomations(options.Automations)
	client.safety.MotionDoorPolicy = normalizedMotionDoorPolicy(
		options.MotionDoorPolicy,
	)
	client.rfConfig = cloneRFConfigOrDefault(options.RF)
	client.osPolicy = cloneOSPolicyOrDefault(options.OSActions)
	client.hostMu.Unlock()
	fqbn := options.FQBN
	if fqbn == "" {
		fqbn = programmer.DefaultFQBN()
	}
	firmwareFeatures, firmwareFeaturesErr := programmer.NormalizeFirmwareFeatures(
		options.FirmwareFeatures,
	)
	client.optionsMu.Lock()
	client.commandOptions = control.CommandOptions{
		ProjectPath: options.ProjectPath, FQBN: fqbn,
		FirmwareFeatures:      firmwareFeatures,
		FirmwareFeaturesError: firmwareFeaturesErr,
		ArduinoCLI:            options.ToolchainCLI, Avrdude: options.Avrdude,
		ArduinoConfig:  options.ToolchainConfig,
		AvrdudeConf:    options.AvrdudeConf,
		AvrdudeBackend: options.AvrdudeBackend, AvrdudeAdapter: options.AvrdudeAdapter,
		Programmer:       options.Programmer,
		HostConfig:       client.currentHostConfig,
		UpdateHostConfig: client.updateHostConfig,
		Outputs:          client.outputs,
	}
	client.optionsMu.Unlock()
	return changed
}

func internalPortIdentity(info *PortInfo) ports.Identity {
	if info == nil {
		return ports.Identity{}
	}
	return ports.Identity{
		Port: info.Name, VID: info.VID, PID: info.PID,
		SerialNumber: info.SerialNumber,
		Name:         firstNonempty(info.FriendlyName, info.Product),
		InstanceID:   info.InstanceID,
	}
}

func firstNonempty(values ...string) string {
	for _, value := range values {
		if strings.TrimSpace(value) != "" {
			return value
		}
	}
	return ""
}

func cloneOSPolicyOrDefault(value hostos.Policy) hostos.Policy {
	if value.VirtualKeys.MinIntervalMS == 0 && value.VirtualKeys.HoldMS == 0 &&
		len(value.VirtualKeys.Allowed) == 0 && len(value.Power.Allowed) == 0 {
		return hostos.DefaultPolicy()
	}
	return hostos.ClonePolicy(value)
}

func (client *Client) currentHostConfig() appconfig.Config {
	client.hostMu.RLock()
	scripts := cloneStringMap(client.scripts)
	automations := cloneAppAutomations(client.automations)
	safety := client.safety
	rfConfig := cloneRFConfigOrDefault(client.rfConfig)
	osPolicy := hostos.ClonePolicy(client.osPolicy)
	client.hostMu.RUnlock()
	config := appconfig.Defaults()
	config.Programming.FirmwareFeatures = append(
		[]programmer.FirmwareFeature(nil),
		client.currentCommandOptions().FirmwareFeatures...,
	)
	config.Macros = client.currentMacros()
	config.StripEffects = client.currentStripEffects()
	config.Scripts = scripts
	config.Automations = automations
	config.Melodies = client.currentMelodies()
	config.StatusEffects = client.currentStatusEffects()
	config.Safety = safety
	config.RF = rfConfig
	config.OSActions = osPolicy
	return config
}

func (client *Client) updateHostConfig(
	change func(*appconfig.Config) error,
) error {
	if change == nil {
		return errors.New("host configuration update callback is nil")
	}
	config := client.currentHostConfig()
	if err := change(&config); err != nil {
		return err
	}
	if err := config.Validate(); err != nil {
		return err
	}
	client.SetOutputDefinitions(config.Melodies, config.StatusEffects)
	client.macroMu.Lock()
	client.macros = cloneAppMacros(config.Macros)
	client.macroMu.Unlock()
	client.outputMu.Lock()
	client.stripEffects = append([]appconfig.StripEffect(nil), config.StripEffects...)
	client.outputMu.Unlock()
	client.hostMu.Lock()
	client.scripts = cloneStringMap(config.Scripts)
	client.automations = cloneAppAutomations(config.Automations)
	client.safety = config.Safety
	client.rfConfig = cloneRFConfigOrDefault(config.RF)
	client.osPolicy = hostos.ClonePolicy(config.OSActions)
	client.hostMu.Unlock()
	client.optionsMu.Lock()
	client.commandOptions.FirmwareFeatures = append(
		[]programmer.FirmwareFeature(nil),
		config.Programming.FirmwareFeatures...,
	)
	client.commandOptions.FirmwareFeaturesError = nil
	client.optionsMu.Unlock()
	return nil
}

func (client *Client) currentCommandOptions() control.CommandOptions {
	client.optionsMu.RLock()
	defer client.optionsMu.RUnlock()
	return client.commandOptions
}

// SetMacros replaces the host-owned macro catalog with a defensive copy.
func (client *Client) SetMacros(macros []Macro) {
	client.macroMu.Lock()
	client.macros = toAppMacros(macros)
	client.macroMu.Unlock()
}

// SetOutputDefinitions replaces the host-owned melody and LED-effect catalogs.
func (client *Client) SetOutputDefinitions(
	melodies []Melody,
	effects []StatusLEDEffect,
) {
	client.outputMu.Lock()
	client.melodies = cloneMelodies(melodies)
	client.statusEffects = append(
		[]appconfig.StatusLEDEffect(nil),
		effects...,
	)
	client.outputMu.Unlock()
}

func (client *Client) currentMelodies() []appconfig.Melody {
	client.outputMu.RLock()
	defer client.outputMu.RUnlock()
	return cloneMelodies(client.melodies)
}

func (client *Client) currentStatusEffects() []appconfig.StatusLEDEffect {
	client.outputMu.RLock()
	defer client.outputMu.RUnlock()
	return append(
		[]appconfig.StatusLEDEffect(nil),
		client.statusEffects...,
	)
}

func (client *Client) currentStripEffects() []appconfig.StripEffect {
	client.outputMu.RLock()
	defer client.outputMu.RUnlock()
	return append([]appconfig.StripEffect(nil), client.stripEffects...)
}

func toAppStripEffects(source []StripEffect) []appconfig.StripEffect {
	if source == nil {
		return appconfig.DefaultStripEffects()
	}
	result := make([]appconfig.StripEffect, len(source))
	for index, effect := range source {
		result[index] = appconfig.StripEffect{
			ID: effect.ID, Name: effect.Name, Category: effect.Category,
			Description: effect.Description, Program: toAppStripProgram(effect.Program),
			DefaultFPS: effect.DefaultFPS, DefaultDurationMS: effect.DefaultDurationMS,
			DefaultPixels: effect.DefaultPixels,
		}
	}
	return result
}

func toAppStripProgram(source StripProgram) appconfig.StripProgram {
	envelope := make([]appconfig.StripEnvelopePoint, len(source.Envelope))
	for index, point := range source.Envelope {
		envelope[index] = appconfig.StripEnvelopePoint{AtMS: point.AtMS, Intensity: point.Intensity}
	}
	return appconfig.StripProgram{
		Primitive: source.Primitive,
		Primary:   appconfig.StripColor{Red: source.Primary.Red, Green: source.Primary.Green, Blue: source.Primary.Blue},
		Secondary: appconfig.StripColor{Red: source.Secondary.Red, Green: source.Secondary.Green, Blue: source.Secondary.Blue},
		PeriodMS:  source.PeriodMS, StepMS: source.StepMS, SwapAfterSteps: source.SwapAfterSteps,
		DimIntensity: source.DimIntensity, TailPixels: source.TailPixels, Envelope: envelope,
	}
}

func (client *Client) currentMacros() []appconfig.Macro {
	client.macroMu.RLock()
	defer client.macroMu.RUnlock()
	return cloneAppMacros(client.macros)
}

func cloneAppMacros(source []appconfig.Macro) []appconfig.Macro {
	result := make([]appconfig.Macro, len(source))
	for index, macro := range source {
		result[index] = macro
		result[index].Steps = append([]appconfig.MacroStep(nil), macro.Steps...)
		for stepIndex := range result[index].Steps {
			result[index].Steps[stepIndex].ActionIDs = append([]string(nil), macro.Steps[stepIndex].ActionIDs...)
		}
	}
	return result
}

func toAppMacros(macros []Macro) []appconfig.Macro {
	result := make([]appconfig.Macro, len(macros))
	for index, macro := range macros {
		result[index] = appconfig.Macro{
			ID: macro.ID, Name: macro.Name, Category: macro.Category,
			Mode: macro.Mode, Color: macro.Color, Label: macro.Label, LCDMessage: macro.LCDMessage,
			TimingToleranceUS:   macro.TimingToleranceUS,
			KeepOutputsOnCancel: macro.KeepOutputsOnCancel,
			BoardProfileKey:     macro.BoardProfileKey,
			BoardProfileMode:    macro.BoardProfileMode,
			Steps:               make([]appconfig.MacroStep, len(macro.Steps)),
			RepeatCount:         macro.RepeatCount, RepeatIntervalMS: macro.RepeatIntervalMS,
		}
		for stepIndex, step := range macro.Steps {
			result[index].Steps[stepIndex] = appconfig.MacroStep{
				AtUS: step.AtUS, Kind: step.Kind,
				Target: step.Target, Value: step.Value,
				DurationMS: step.DurationMS, ToValue: step.ToValue,
				Easing: step.Easing, SampleRateHz: step.SampleRateHz,
				FrequencyHz: step.FrequencyHz,
				Text:        step.Text, Destination: step.Destination,
				Code: step.Code, Bits: step.Bits, Protocol: step.Protocol,
				PulseUS: step.PulseUS, Red: step.Red, Green: step.Green,
				Blue: step.Blue, Brightness: step.Brightness,
				ToRed: step.ToRed, ToGreen: step.ToGreen, ToBlue: step.ToBlue,
				ToBrightness: step.ToBrightness,
				Opcode:       step.Opcode, PayloadHex: step.PayloadHex,
				ActionIDs: append([]string(nil), step.ActionIDs...),
			}
		}
	}
	return result
}

func toAppAutomations(source []Automation) []appconfig.Automation {
	result := make([]appconfig.Automation, len(source))
	for index, automation := range source {
		result[index] = appconfig.Automation{
			Name: automation.Name, Enabled: automation.Enabled,
			CooldownMS: automation.CooldownMS,
			Match: appconfig.AutomationMatch{
				Kind: automation.Match.Kind, Lifecycle: automation.Match.Lifecycle,
				State: automation.Match.State, Contains: automation.Match.Contains,
				Key: automation.Match.Key, Gesture: automation.Match.Gesture,
				Source: automation.Match.Source, RFID: automation.Match.RFID,
				RFCode:     automation.Match.RFCode,
				RFProtocol: automation.Match.RFProtocol,
				RFBits:     automation.Match.RFBits,
			},
			Actions: make([]appconfig.AutomationAction, len(automation.Actions)),
		}
		for actionIndex, action := range automation.Actions {
			result[index].Actions[actionIndex] = appconfig.AutomationAction{
				Type: action.Type, Command: action.Command, Macro: action.Macro,
				Executable: action.Executable,
				Detached:   action.Detached,
				Args:       append([]string(nil), action.Args...),
				Script:     action.Script,
				Event:      action.Event,
				VirtualKey: action.VirtualKey,
				HoldMS:     action.HoldMS,
				Power:      action.Power,
				Confirm:    action.Confirm,
				AppKind:    action.AppKind, AppValue: action.AppValue, AppTarget: action.AppTarget,
				ActionID: action.ActionID,
			}
			if action.RF != nil {
				result[index].Actions[actionIndex].RF = &appconfig.RFTransmit{
					Code: action.RF.Code, Bits: action.RF.Bits,
					Protocol: action.RF.Protocol, PulseUS: action.RF.PulseUS,
					Repeats: action.RF.Repeats,
				}
			}
		}
	}
	return result
}

func cloneAppAutomations(source []appconfig.Automation) []appconfig.Automation {
	result := make([]appconfig.Automation, len(source))
	for index, automation := range source {
		result[index] = automation
		result[index].Actions = make(
			[]appconfig.AutomationAction,
			len(automation.Actions),
		)
		for actionIndex, action := range automation.Actions {
			result[index].Actions[actionIndex] = action
			result[index].Actions[actionIndex].Args =
				append([]string(nil), action.Args...)
			if action.RF != nil {
				rf := *action.RF
				result[index].Actions[actionIndex].RF = &rf
			}
		}
		if automation.Match.RFID != nil {
			id := *automation.Match.RFID
			result[index].Match.RFID = &id
		}
		if automation.Match.RFCode != nil {
			code := *automation.Match.RFCode
			result[index].Match.RFCode = &code
		}
	}
	return result
}

func cloneStringMap(source map[string]string) map[string]string {
	result := make(map[string]string, len(source))
	for key, value := range source {
		result[key] = value
	}
	return result
}

func cloneMelodies(source []appconfig.Melody) []appconfig.Melody {
	result := make([]appconfig.Melody, len(source))
	for index, melody := range source {
		result[index] = melody
		result[index].Notes = append(
			[]appconfig.MelodyNote(nil),
			melody.Notes...,
		)
	}
	return result
}

func cloneRFConfigOrDefault(source appconfig.RFConfig) appconfig.RFConfig {
	if strings.TrimSpace(source.DisplayRadix) == "" {
		source = appconfig.DefaultRFConfig()
	}
	result := source
	result.Categories = append([]appconfig.RFCategory(nil), source.Categories...)
	result.Metadata = append([]appconfig.RFMetadata(nil), source.Metadata...)
	return result
}

// ConfigureRFPresentation replaces host-only RF names, categories, and radix.
func (client *Client) ConfigureRFPresentation(config RFConfig) {
	client.hostMu.Lock()
	client.rfConfig = cloneRFConfigOrDefault(config)
	client.hostMu.Unlock()
}

// RFPresentation returns a defensive copy of host-owned RF presentation data.
func (client *Client) RFPresentation() RFConfig {
	client.hostMu.RLock()
	defer client.hostMu.RUnlock()
	return cloneRFConfigOrDefault(client.rfConfig)
}

func normalizedMotionDoorPolicy(value string) string {
	value = strings.ToLower(strings.TrimSpace(value))
	switch value {
	case "open", "closed", "never", "always":
		return value
	default:
		return "always"
	}
}

// Connect resumes automatic discovery and authenticates the selected board.
func (client *Client) Connect(ctx context.Context) error {
	return client.runtime.Connect(ctx)
}

// Open connects directly to a named serial port and authenticates the board.
func (client *Client) Open(ctx context.Context, port string) error {
	return client.runtime.Open(ctx, port)
}

// SetDeviceObserver receives authenticated device identities after connection.
func (client *Client) SetDeviceObserver(
	observer func(PortInfo, Hello),
) {
	if observer == nil {
		client.runtime.SetDeviceObserver(nil)
		return
	}
	client.runtime.SetDeviceObserver(func(info ports.Info, hello native.Hello) {
		observer(publicPortInfo(info), hello)
	})
}

// Close stops active output streams and intentionally closes the serial port.
func (client *Client) Close() error {
	client.outputs.StopAll()
	releaseContext, cancel := context.WithTimeout(context.Background(), 2*time.Second)
	defer cancel()
	_, releaseErr := client.outputs.ReleaseStatusEffect(releaseContext)
	return errors.Join(releaseErr, client.runtime.Close())
}

// PulseResetFor briefly asserts the adapter reset lines, then reauthenticates
// the native application after Urboot has released the UART.
func (client *Client) PulseResetFor(
	ctx context.Context,
	duration time.Duration,
) error {
	if duration <= 0 || duration > 5*time.Second {
		return errors.New("reset pulse must be positive and at most five seconds")
	}
	if err := client.runtime.PulseResetFor(ctx, duration); err != nil {
		return err
	}
	return client.runtime.Reconnect(ctx, "DTR reset pulse completed over IPC")
}

// Shutdown closes the serial port and releases background event forwarding.
// If closing the transport fails, Shutdown retains ownership and may be retried.
// After a successful shutdown, the client must not be reused.
func (client *Client) Shutdown() error {
	client.shutdownMu.Lock()
	defer client.shutdownMu.Unlock()
	client.outputs.StopAll()
	releaseContext, cancel := context.WithTimeout(context.Background(), 2*time.Second)
	_, releaseErr := client.outputs.ReleaseStatusEffect(releaseContext)
	cancel()
	if releaseErr != nil {
		return fmt.Errorf("release status LED ownership before shutdown: %w", releaseErr)
	}
	if err := client.runtimeClose(); err != nil {
		return err
	}
	if err := client.outputs.Close(); err != nil {
		return fmt.Errorf("close output scheduler: %w", err)
	}
	_ = hostos.DefaultExecutor.ReleaseAll()
	client.doneOnce.Do(func() { close(client.done) })
	return nil
}

// Execute runs one command through the same engine exposed by every host surface.
func (client *Client) Execute(ctx context.Context, command string) (string, error) {
	client.engineMu.Lock()
	defer client.engineMu.Unlock()
	return client.engine.Execute(ctx, command)
}

// BuildFirmware compiles the configured canonical project without accepting
// an arbitrary remote filesystem path or raw compiler flags.
func (client *Client) BuildFirmware(
	ctx context.Context,
	request FirmwareBuildRequest,
) (result FirmwareBuildResult, buildErr error) {
	operationBytes := make([]byte, 12)
	if _, err := rand.Read(operationBytes); err != nil {
		return result, fmt.Errorf("create firmware build operation ID: %w", err)
	}
	operationID := "firmware-build-" + hex.EncodeToString(operationBytes)
	result.OperationID = operationID
	options := client.currentCommandOptions()
	phase := func(state string, failure error) {
		if client.runtime == nil {
			return
		}
		metadata := map[string]string{"operation_id": operationID, "operation": "compile", "method": "compile", "state": state}
		if failure != nil {
			metadata["error"] = failure.Error()
		}
		client.runtime.PublishStructuredEvent(control.Event{Kind: "program." + state, Stream: control.EventStreamActivity,
			Text: "firmware compile " + state, Metadata: metadata})
	}
	phase("started", nil)
	defer func() {
		if buildErr != nil {
			buildErr = errors.New(control.NormalizeProgramError(buildErr.Error(), options.ProjectPath, options.ArduinoCLI, options.ArduinoConfig))
			phase("failed", buildErr)
		} else {
			phase("completed", nil)
		}
	}()
	if len(request.FirmwareFeatures) != 0 && request.NoFirmwareFeatures {
		return result, errors.New(
			"firmware_features and no_firmware_features are mutually exclusive",
		)
	}
	features, err := programmer.NormalizeFirmwareFeatures(request.FirmwareFeatures)
	if err != nil {
		return result, err
	}
	words := []string{"program", "compile", "."}
	if request.NoFirmwareFeatures {
		words = append(words, "--no-firmware-features")
	} else {
		for _, feature := range programmer.FirmwareFeatureNames(features) {
			words = append(words, "--firmware-feature", feature)
		}
	}
	output, buildErr := client.Execute(
		control.WithProgramOperationID(ctx, operationID),
		strings.Join(words, " "),
	)
	result.Output = control.NormalizeProgramOutput(output, options.ProjectPath, options.ArduinoCLI, options.ArduinoConfig)
	return result, buildErr
}

// CommandCatalog exposes the same discoverable command contract used by the
// shell, primary IPC, REST, WebSocket RPC, and the C-compatible library.
func (client *Client) CommandCatalog() []CommandDescriptor {
	client.engineMu.Lock()
	defer client.engineMu.Unlock()
	return client.engine.Catalog()
}

// ProgramState returns the host-owned application state. Hardware conditions
// such as the enclosure door are intentionally not state owners.
func (client *Client) ProgramState() ProgramStateSnapshot {
	return client.runtime.ProgramState()
}

// SetProgramState updates host-owned Idle or Running state for a named owner.
func (client *Client) SetProgramState(
	owner string,
	mode ProgramMode,
	reason string,
) (ProgramStateSnapshot, error) {
	return client.runtime.SetProgramState(owner, mode, reason)
}

// AcquireProgramState holds Running state until the returned lease is released.
func (client *Client) AcquireProgramState(
	owner string,
	reason string,
) (*ProgramStateLease, ProgramStateSnapshot, error) {
	return client.runtime.AcquireProgramState(owner, reason)
}

// Status requests one fresh native telemetry snapshot from the board.
func (client *Client) Status(ctx context.Context) (Status, error) {
	return client.runtime.RefreshStatus(ctx)
}

// SetBoardSilent applies and verifies the MCU Silent bit through the sole
// serial-owning runtime.
func (client *Client) SetBoardSilent(ctx context.Context, silent bool) (Settings, error) {
	return client.runtime.SetBoardSilent(ctx, silent)
}

// SubscribeStatus polls only while the returned subscription context is
// alive. Merely keeping the serial protocol connected never starts polling.
func (client *Client) SubscribeStatus(
	ctx context.Context,
	interval time.Duration,
) (<-chan StatusUpdate, error) {
	if interval < 50*time.Millisecond || interval > time.Minute {
		return nil, errors.New("status subscription interval must be 50ms..1m")
	}
	updates := make(chan StatusUpdate, 1)
	client.statusHub.mu.Lock()
	if client.statusHub.subscribers == nil {
		client.statusHub.subscribers = make(map[uint64]*statusSubscriber)
		client.statusHub.wake = make(chan struct{}, 1)
	}
	client.statusHub.nextID++
	id := client.statusHub.nextID
	client.statusHub.subscribers[id] = &statusSubscriber{
		interval: interval, next: time.Now(), updates: updates,
	}
	if !client.statusHub.running {
		client.statusHub.running = true
		go client.runStatusSubscriptionHub()
	}
	wake := client.statusHub.wake
	client.statusHub.mu.Unlock()
	select {
	case wake <- struct{}{}:
	default:
	}
	go func() {
		<-ctx.Done()
		client.statusHub.mu.Lock()
		if subscriber, ok := client.statusHub.subscribers[id]; ok {
			delete(client.statusHub.subscribers, id)
			close(subscriber.updates)
		}
		client.statusHub.mu.Unlock()
		select {
		case wake <- struct{}{}:
		default:
		}
	}()
	return updates, nil
}

// runStatusSubscriptionHub performs at most one physical status query at each
// fastest requested cadence, then fans that authoritative result out according
// to each subscriber's interval. Additional Web/TUI clients never multiply
// serial traffic.
func (client *Client) runStatusSubscriptionHub() {
	for {
		client.statusHub.mu.Lock()
		if len(client.statusHub.subscribers) == 0 {
			client.statusHub.running = false
			client.statusHub.mu.Unlock()
			return
		}
		now := time.Now()
		next := now.Add(time.Minute)
		for _, subscriber := range client.statusHub.subscribers {
			if subscriber.next.Before(next) {
				next = subscriber.next
			}
		}
		wake := client.statusHub.wake
		client.statusHub.mu.Unlock()

		delay := time.Until(next)
		if delay > 0 {
			timer := time.NewTimer(delay)
			select {
			case <-timer.C:
			case <-wake:
				if !timer.Stop() {
					select {
					case <-timer.C:
					default:
					}
				}
				continue
			}
		}

		at := time.Now()
		requestContext, cancel := context.WithTimeout(context.Background(), 1500*time.Millisecond)
		status, err := client.statusForSubscription(requestContext)
		if err == nil {
			client.refreshIllumination(requestContext, status)
		}
		cancel()
		update := StatusUpdate{Time: at, Status: status}
		var busy *control.ResourceBusyError
		deferred := errors.As(err, &busy) && busy.Resource == "serial_channel" && busy.Owner == "media_timeline"
		if err != nil {
			update.Error = err.Error()
		}
		client.statusHub.mu.Lock()
		for _, subscriber := range client.statusHub.subscribers {
			if subscriber.next.After(at) {
				continue
			}
			for !subscriber.next.After(at) {
				subscriber.next = subscriber.next.Add(subscriber.interval)
			}
			if deferred {
				// No query reached the board. Advance cadence without inventing a
				// fresh sample or publishing a controller.error to every player.
				continue
			}
			if err != nil {
				backoff := at.Add(time.Second)
				if subscriber.next.Before(backoff) {
					subscriber.next = backoff
				}
			}
			select {
			case subscriber.updates <- update:
			default:
				select {
				case <-subscriber.updates:
				default:
				}
				select {
				case subscriber.updates <- update:
				default:
				}
			}
		}
		client.statusHub.mu.Unlock()
	}
}

func (client *Client) statusForSubscription(ctx context.Context) (Status, error) {
	if client.statusFetch != nil {
		return client.statusFetch(ctx)
	}
	return client.Status(ctx)
}

const enclosureIlluminationPWMChannel byte = 11

func illuminationPWM(brightness byte) uint16 {
	scaled := uint32(brightness)*16 + uint32(brightness)/16
	// Brightness is an 8-bit value, so scaled is mathematically bounded by
	// the PCA9685 full-scale value. Keep the bound explicit at the narrowing
	// point so callers, static analysis, and future type changes all preserve
	// the hardware contract.
	if scaled > 4095 {
		return 4095
	}
	return uint16(scaled)
}

func illuminationBrightness(pwm uint16) byte {
	if pwm >= 4095 {
		return 255
	}
	return byte((uint32(pwm)*16 + 128) / 257)
}

func illuminationState(
	settings Settings,
	status Status,
	pwm PWMValues,
	updatedAt time.Time,
) IlluminationState {
	target := settings.OffBrightness
	switch settings.LightMode {
	case 1:
		if status.DoorOpen {
			target = settings.OnBrightness
		}
	case 2:
		target = settings.OnBrightness
	}
	targetPWM := illuminationPWM(target)
	appliedPWM := pwm.Values[enclosureIlluminationPWMChannel]
	return IlluminationState{
		Available:         pwm.Available && status.PWMAvailable,
		Mode:              settings.LightMode,
		OnBrightness:      settings.OnBrightness,
		OffBrightness:     settings.OffBrightness,
		DoorOpen:          status.DoorOpen,
		TargetBrightness:  target,
		TargetPWM:         targetPWM,
		AppliedBrightness: illuminationBrightness(appliedPWM),
		AppliedPWM:        appliedPWM,
		AtTarget:          appliedPWM == targetPWM,
		Persisted:         settings.Persisted,
		UpdatedAt:         updatedAt,
	}
}

func sameIlluminationState(left, right IlluminationState) bool {
	left.UpdatedAt = time.Time{}
	right.UpdatedAt = time.Time{}
	return left == right
}

func (client *Client) observeIllumination(state IlluminationState) {
	client.illuminationMu.Lock()
	previous := client.illumination
	changed := !sameIlluminationState(previous, state)
	client.illumination = state
	client.illuminationMu.Unlock()
	if !changed || client.runtime == nil {
		return
	}
	client.runtime.PublishStructuredEvent(control.Event{
		Kind:   "illumination.changed",
		Stream: control.EventStreamState,
		Text: fmt.Sprintf(
			"enclosure illumination applied %d/4095 toward %d/4095",
			state.AppliedPWM,
			state.TargetPWM,
		),
		Metadata: map[string]string{
			"mode":               strconv.Itoa(int(state.Mode)),
			"door_open":          strconv.FormatBool(state.DoorOpen),
			"on_brightness":      strconv.Itoa(int(state.OnBrightness)),
			"off_brightness":     strconv.Itoa(int(state.OffBrightness)),
			"target_brightness":  strconv.Itoa(int(state.TargetBrightness)),
			"target_pwm":         strconv.Itoa(int(state.TargetPWM)),
			"applied_brightness": strconv.Itoa(int(state.AppliedBrightness)),
			"applied_pwm":        strconv.Itoa(int(state.AppliedPWM)),
			"at_target":          strconv.FormatBool(state.AtTarget),
			"persisted":          strconv.FormatBool(state.Persisted),
		},
	})
}

func (client *Client) refreshIllumination(ctx context.Context, status Status) {
	if client.runtime == nil {
		return
	}
	snapshot := client.runtime.Snapshot()
	if !snapshot.Connected || !snapshot.HaveSettings || !status.PWMAvailable {
		return
	}
	now := time.Now()
	client.illuminationMu.Lock()
	if now.Before(client.illuminationPollAt) {
		client.illuminationMu.Unlock()
		return
	}
	// Ten authoritative samples per second are visually responsive for the
	// 20 ms firmware fade while avoiding a 34-byte UART response per high-rate
	// TUI subscriber tick.
	client.illuminationPollAt = now.Add(100 * time.Millisecond)
	client.illuminationMu.Unlock()
	pwm, err := client.PWMValues(ctx)
	if err != nil || !pwm.Available {
		return
	}
	client.observeIllumination(illuminationState(snapshot.Settings, status, pwm, now))
}

// ConfigureHistory updates bounded telemetry retention and persistence policy.
func (client *Client) ConfigureHistory(options HistoryOptions) error {
	return client.runtime.ConfigureHistory(options)
}

// ConfigureLCDPresentation updates host-owned LCD discovery and fallback policy.
func (client *Client) ConfigureLCDPresentation(
	options LCDPresentationOptions,
) error {
	return client.runtime.LCDPresenter().Configure(options)
}

// MirrorLCDPrompt publishes two prompt lines through the LCD presenter.
func (client *Client) MirrorLCDPrompt(line1, line2 string) {
	client.runtime.LCDPresenter().MirrorPrompt(line1, line2)
}

// ShowLCDPriority temporarily replaces ordinary LCD content by event priority.
func (client *Client) ShowLCDPriority(
	kind, line1, line2 string,
	hold time.Duration,
) bool {
	return client.runtime.LCDPresenter().ShowPriority(
		kind,
		line1,
		line2,
		hold,
	)
}

// LCDPresentationState returns the current address, visibility, and fallback state.
func (client *Client) LCDPresentationState() LCDPresentationState {
	return client.runtime.LCDPresenter().State()
}

// StatusHistory returns retained telemetry at or after since.
func (client *Client) StatusHistory(since time.Time) []StatusSample {
	return client.runtime.StatusHistory(since)
}

// Timeline returns retained device and host events in chronological order.
func (client *Client) Timeline(since time.Time, limit int) []TimelineEntry {
	return client.runtime.Timeline(since, limit)
}

// SetMenuPage navigates directly to one stable board menu ID.
func (client *Client) SetMenuPage(ctx context.Context, page byte) error {
	if page > 127 {
		return errors.New("menu page must fit seven bits; use SetVolatileMenuPage for mirrored navigation")
	}
	return client.runtime.Command(ctx, native.OpMenuSetPage, []byte{page})
}

// SetVolatileMenuPage cannot silently fall back to the older EEPROM-writing
// navigation request. A peer must advertise support in its live HELLO.
func (client *Client) SetVolatileMenuPage(ctx context.Context, page byte) error {
	if client.Snapshot().Hello.BuildFeatures&native.BuildFeatureVolatileMenu == 0 {
		return errors.New("firmware does not advertise volatile menu navigation")
	}
	if page > 127 {
		return errors.New("volatile menu page must fit seven bits")
	}
	return client.runtime.Command(ctx, native.OpMenuSetPage, []byte{page | 0x80})
}

// PresentMirrorSegments takes a bounded two-second presentation lease. It
// changes cells only, never EEPROM brightness or physical detection state.
func (client *Client) PresentMirrorSegments(ctx context.Context, cells [4]byte, revision uint64) error {
	if client.Snapshot().Hello.Capabilities&native.CapabilityScheduledSegments == 0 {
		return errors.New("firmware does not advertise scheduled segments")
	}
	return client.runtime.PresentMirrorSegments(ctx, cells, revision)
}

func (client *Client) SegmentRevision() uint64 { return client.runtime.SegmentRevision() }

// BoardName reads the operator-assigned MCU EEPROM name.
func (client *Client) BoardName(ctx context.Context) (BoardName, error) {
	return client.runtime.BoardName(ctx)
}

// SetBoardName persists and verifies up to eight printable ASCII characters.
// Passing an empty string clears the name.
func (client *Client) SetBoardName(ctx context.Context, name string) (BoardName, error) {
	return client.runtime.SetBoardName(ctx, name)
}

// SetMenuPageByName resolves a live catalog name or ID before navigating.
func (client *Client) SetMenuPageByName(
	ctx context.Context,
	reference string,
) (MenuPageInfo, error) {
	catalog, err := client.MenuCatalog(ctx)
	if err != nil {
		return MenuPageInfo{}, err
	}
	page, err := control.ResolveMenuPageIn(catalog.Pages, reference)
	if err != nil {
		return MenuPageInfo{}, err
	}
	if err := client.SetMenuPage(ctx, page.ID); err != nil {
		return MenuPageInfo{}, err
	}
	return page, nil
}

// MenuCatalog queries the board-authoritative page directory and active page.
func (client *Client) MenuCatalog(ctx context.Context) (MenuCatalog, error) {
	return control.QueryMenuCatalog(ctx, client.runtime)
}

// MenuLayout returns the persisted MCU layout when capability bit 23 is
// present, or a clearly marked read-only catalog-order fallback on older
// firmware.
func (client *Client) MenuLayout(ctx context.Context) (MenuLayout, error) {
	return control.QueryMenuLayout(ctx, client.runtime)
}

// SetMenuLayout validates a complete stable-ID permutation and visibility
// mask, writes MCU EEPROM, and verifies the board's exact readback.
func (client *Client) SetMenuLayout(ctx context.Context, layout MenuLayout) (MenuLayout, error) {
	return control.PersistMenuLayout(ctx, client.runtime, layout)
}

// ReplaceHostMenuDirectory installs one volatile generation on firmware that
// advertises capability bit 24. It never writes MCU EEPROM.
func (client *Client) ReplaceHostMenuDirectory(ctx context.Context, directory HostMenuDirectory) error {
	return client.runtime.ReplaceHostMenuDirectory(ctx, directory)
}

// PushHostMenuContent supplies one volatile host-menu value to the front panel.
func (client *Client) PushHostMenuContent(ctx context.Context, content HostMenuContent) error {
	return client.runtime.PushHostMenuContent(ctx, content)
}

// HostMenuState queries the active host-menu generation and selection.
func (client *Client) HostMenuState(ctx context.Context) (HostMenuState, error) {
	return client.runtime.HostMenuState(ctx)
}

// MenuPages returns the built-in stable menu metadata known to this host build.
func MenuPages() []MenuPageInfo { return control.MenuPages() }

// I2CTransfer exposes the firmware's bounded cooperative I2C lease to Go API
// consumers. MCU-owned sensor/PWM service remains authoritative outside the
// short requested lease.
func (client *Client) I2CTransfer(
	ctx context.Context,
	address, leaseSeconds byte,
	write []byte,
	readLength byte,
) (I2CTransferResult, error) {
	return control.TransferI2C(ctx, client.runtime, address, leaseSeconds, write, readLength)
}

// ScanI2C probes all valid seven-bit addresses through the cooperative lease.
func (client *Client) ScanI2C(ctx context.Context) ([]byte, error) {
	return control.ScanI2C(ctx, client.runtime)
}

// RescanLCD probes configured LCD addresses and returns the detected address.
func (client *Client) RescanLCD(ctx context.Context) (byte, error) {
	return client.runtime.LCDPresenter().RescanPhysical(ctx)
}

// SetRelay controls the human-facing R1..R8 relay number. The firmware remains
// the authority for the R1..R4 motion interlock.
func (client *Client) SetRelay(
	ctx context.Context,
	relayNumber byte,
	active bool,
) error {
	if relayNumber < 1 || relayNumber > 8 {
		return fmt.Errorf("relay number %d is outside R1..R8", relayNumber)
	}
	if active && relayNumber <= 4 {
		if err := client.requireMotionAllowed(ctx); err != nil {
			return err
		}
	}
	return client.runtime.SetRelay(ctx, relayNumber-1, active)
}

// SetMotionSide requests interlocked Up, Down, or Stop for side 1 or 2.
func (client *Client) SetMotionSide(
	ctx context.Context,
	sideNumber byte,
	motion RelayMotion,
) error {
	if sideNumber < 1 || sideNumber > 2 {
		return fmt.Errorf("motion side %d is outside 1..2", sideNumber)
	}
	payload, err := native.RelaySidePayload(
		sideNumber-1,
		byte(motion),
	)
	if err != nil {
		return err
	}
	if motion != RelayMotionStop {
		if err := client.requireMotionAllowed(ctx); err != nil {
			return err
		}
	}
	return client.runtime.Command(ctx, native.OpRelaySide, payload)
}

// ToggleRelay returns the newly requested state. It obtains a fresh status
// first; an R1..R4 off-to-on transition is rejected unless that same reply
// confirms the enclosure door is open.
func (client *Client) ToggleRelay(
	ctx context.Context,
	relayNumber byte,
) (bool, error) {
	if relayNumber < 1 || relayNumber > 8 {
		return false, fmt.Errorf(
			"relay number %d is outside R1..R8",
			relayNumber,
		)
	}
	status, err := client.runtime.RefreshStatus(ctx)
	if err != nil {
		return false, fmt.Errorf("query relay state for toggle: %w", err)
	}
	active := status.ActiveRelays&(1<<(relayNumber-1)) == 0
	if active && relayNumber <= 4 {
		if err := client.checkMotionDoorPolicy(status); err != nil {
			return false, err
		}
	}
	if err := client.runtime.SetRelay(ctx, relayNumber-1, active); err != nil {
		return false, err
	}
	return active, nil
}

func (client *Client) requireMotionAllowed(ctx context.Context) error {
	policy := client.motionDoorPolicy()
	if policy == "always" {
		return nil
	}
	if policy == "never" {
		return errors.New("motion command rejected by PC safety policy (never)")
	}
	status, err := client.runtime.RefreshStatus(ctx)
	if err != nil {
		return fmt.Errorf(
			"motion command rejected because the door policy could not be verified: %w",
			err,
		)
	}
	return client.checkMotionDoorPolicy(status)
}

func (client *Client) motionDoorPolicy() string {
	client.hostMu.RLock()
	defer client.hostMu.RUnlock()
	return normalizedMotionDoorPolicy(client.safety.MotionDoorPolicy)
}

func (client *Client) checkMotionDoorPolicy(status Status) error {
	switch policy := client.motionDoorPolicy(); policy {
	case "always":
		return nil
	case "open":
		if status.DoorOpen {
			return nil
		}
		return errors.New("motion command rejected while enclosure door is closed")
	case "closed":
		if !status.DoorOpen {
			return nil
		}
		return errors.New("motion command rejected while enclosure door is open")
	case "never":
		return errors.New("motion command rejected by PC safety policy (never)")
	default:
		return fmt.Errorf("motion command rejected: unknown PC safety policy %q", policy)
	}
}

// AllRelaysOff immediately requests the firmware's all-relays-off path.
func (client *Client) AllRelaysOff(ctx context.Context) error {
	return client.runtime.Command(ctx, native.OpRelayAllOff, nil)
}

// EmergencyStop returns the host-authoritative motion/effect interlock state.
func (client *Client) EmergencyStop() EmergencyStopState {
	return client.runtime.EmergencyStop()
}

// SetEmergencyStop engages or releases the PCController-wide command latch.
// Releasing it never resumes cancelled effects or motion automatically.
func (client *Client) SetEmergencyStop(ctx context.Context, active bool, source, reason string) (EmergencyStopState, error) {
	return client.runtime.SetEmergencyStop(ctx, active, source, reason)
}

// PWMChannelConfig describes logical intensity conversion and action steps.
type PWMChannelConfig = appconfig.PWMChannelConfig

// ApplyPWMAction applies an advertised logical percentage action to the exact
// connection generation and publishes authoritative all-channel readback.
func (client *Client) ApplyPWMAction(ctx context.Context, generation uint64, channel byte, verb string, config PWMChannelConfig) (PWMValues, error) {
	values, err := client.runtime.ApplyPWMAction(ctx, generation, channel, verb, config)
	if err != nil {
		return PWMValues{}, err
	}
	if client.runtime.Snapshot().ConnectionGeneration != generation {
		return PWMValues{}, errors.New("connection changed before PWM action readback publication")
	}
	return values, nil
}

// ApplyPWMAllOff is the confirmed operator route, including configured recall
// persistence. AllPWMOff remains the native zeroing primitive for safe cleanup.
func (client *Client) ApplyPWMAllOff(ctx context.Context, generation uint64) (PWMValues, error) {
	return client.runtime.ApplyPWMAllOff(ctx, generation)
}

// SetPWMChannel controls a native logical PWM channel 0..15 at 0..4095.
func (client *Client) SetPWMChannel(
	ctx context.Context,
	channel byte,
	value uint16,
) error {
	payload, err := native.PWMSetPayload(channel, value)
	if err != nil {
		return err
	}
	return client.runtime.Command(ctx, native.OpPWMSet, payload)
}

// AllPWMOff requests zero for every logical PWM channel.
func (client *Client) AllPWMOff(ctx context.Context) error {
	return client.runtime.Command(ctx, native.OpPWMAllOff, nil)
}

type PWMWriteTrace = control.PWMWriteTrace

func (client *Client) StartPWMWriteTrace(channel byte, duration time.Duration) (PWMWriteTrace, error) {
	return client.runtime.StartPWMWriteTrace(channel, duration)
}

func (client *Client) StopPWMWriteTrace() PWMWriteTrace { return client.runtime.StopPWMWriteTrace() }
func (client *Client) PWMWriteTrace() PWMWriteTrace     { return client.runtime.PWMWriteTrace() }

// PWMValues requests all logical PWM values and controller availability.
func (client *Client) PWMValues(ctx context.Context) (PWMValues, error) {
	frame, err := client.runtime.Request(
		ctx,
		native.OpPWMGet,
		nil,
		native.OpPWMValues,
	)
	if err != nil {
		return PWMValues{}, err
	}
	values, err := native.ParsePWMValues(frame.Payload)
	if err != nil {
		return PWMValues{}, err
	}
	return values, nil
}

// PublishPWMValues broadcasts one authoritative all-channel PWM readback to
// every subscribed UI/client. PWMValues calls it after parsing the board frame;
// embedders that already hold an equivalent board readback may also publish it
// without issuing another serial transaction.
func (client *Client) PublishPWMValues(values PWMValues) {
	client.runtime.PublishPWMValues(values)
}

// Illumination reads the persisted policy, live door state, and exact applied
// enclosure PWM value through one typed host surface.
func (client *Client) Illumination(ctx context.Context) (IlluminationState, error) {
	settings, err := client.runtime.Settings(ctx)
	if err != nil {
		return IlluminationState{}, fmt.Errorf("read illumination settings: %w", err)
	}
	status, err := client.Status(ctx)
	if err != nil {
		return IlluminationState{}, fmt.Errorf("read illumination status: %w", err)
	}
	pwm, err := client.PWMValues(ctx)
	if err != nil {
		return IlluminationState{}, fmt.Errorf("read illumination PWM: %w", err)
	}
	if !pwm.Available || !status.PWMAvailable {
		return IlluminationState{}, errors.New("enclosure illumination PWM is unavailable")
	}
	state := illuminationState(settings, status, pwm, time.Now())
	client.observeIllumination(state)
	return state, nil
}

// SetIllumination changes only the three enclosure-light policy fields,
// preserves every unrelated setting, waits for EEPROM durability, and returns
// an independently read-back live state.
func (client *Client) SetIllumination(
	ctx context.Context,
	mode, onBrightness, offBrightness byte,
) (IlluminationState, error) {
	desired, err := client.runtime.Settings(ctx)
	if err != nil {
		return IlluminationState{}, fmt.Errorf("read settings before illumination write: %w", err)
	}
	desired.LightMode = mode
	desired.OnBrightness = onBrightness
	desired.OffBrightness = offBrightness
	if _, err := client.runtime.SetSettings(ctx, desired); err != nil {
		return IlluminationState{}, fmt.Errorf("apply illumination settings: %w", err)
	}
	return client.Illumination(ctx)
}

// OverrideIllumination applies an exact raw value to the dedicated enclosure
// MOSFET output and returns an authoritative readback. It deliberately leaves
// the persisted Off/Auto/On policy untouched: the enclosure-light controller
// remains the owner and may reassert its selected target on the next policy
// transition.
func (client *Client) OverrideIllumination(
	ctx context.Context,
	value uint16,
) (IlluminationState, error) {
	return client.overrideIllumination(ctx, value, client.SetPWMChannel, client.Illumination)
}

func (client *Client) overrideIllumination(
	ctx context.Context,
	value uint16,
	set func(context.Context, byte, uint16) error,
	read func(context.Context) (IlluminationState, error),
) (IlluminationState, error) {
	if value > 4095 {
		return IlluminationState{}, fmt.Errorf("enclosure illumination PWM must be 0..4095")
	}
	if err := set(ctx, enclosureIlluminationPWMChannel, value); err != nil {
		return IlluminationState{}, fmt.Errorf("apply enclosure illumination override: %w", err)
	}
	state, err := read(ctx)
	if err != nil {
		return IlluminationState{}, err
	}
	client.observeIllumination(state)
	return state, nil
}

// SetStatusRGB replaces the base status color and cancels an active overlay.
func (client *Client) SetStatusRGB(
	ctx context.Context,
	red, green, blue, brightness byte,
) error {
	return client.outputs.ReplaceStatusRGB(ctx, red, green, blue, brightness)
}

// SetStatusRGBBase updates the host state-policy color without canceling a
// user-requested overlay effect. The scheduler restores it after the overlay.
func (client *Client) SetStatusRGBBase(
	ctx context.Context,
	red, green, blue, brightness byte,
) error {
	return client.outputs.SetStatusBase(control.WithBackgroundCommand(ctx), red, green, blue, brightness)
}

// ClearStatusRGBBase clears cached host fallback policy without altering an
// explicit board preview/effect or emitting a wire command.
func (client *Client) ClearStatusRGBBase() {
	client.outputs.ClearStatusBase()
}

// OutputState returns active melody and status-effect operation metadata.
func (client *Client) OutputState() OutputStreamState {
	return client.outputs.State()
}

// PlayTone sends one bounded buzzer tone after stopping streamed melody playback.
func (client *Client) PlayTone(
	ctx context.Context,
	frequencyHz, durationMS uint16,
) error {
	if durationMS == 0 {
		return errors.New("tone duration must be nonzero")
	}
	if frequencyHz != 0 && (frequencyHz < 20 || frequencyHz > 20000) {
		return fmt.Errorf("tone frequency must be 0 or 20..20000 Hz")
	}
	client.outputs.StopMelody()
	return client.runtime.Command(
		ctx,
		native.OpBuzzer,
		native.BuzzerPayload(frequencyHz, durationMS),
	)
}

// StartMelody begins asynchronous playback; zero repeats until StopMelody.
func (client *Client) StartMelody(
	ctx context.Context,
	melody Melody,
	repeats int,
) (OutputOperation, error) {
	operation, err := client.outputs.StartMelody(ctx, melody, repeats)
	return publicOutputOperation(operation), err
}

// ConfiguredMelodies returns the effective named melody catalog.
func (client *Client) ConfiguredMelodies() []Melody {
	return appconfig.EffectiveMelodies(client.currentHostConfig())
}

// StartConfiguredMelody begins a named melody; zero repeats until stopped.
func (client *Client) StartConfiguredMelody(
	ctx context.Context,
	name string,
	repeats int,
) (OutputOperation, error) {
	for _, melody := range client.ConfiguredMelodies() {
		if strings.EqualFold(strings.TrimSpace(melody.Name), strings.TrimSpace(name)) {
			return client.StartMelody(ctx, melody, repeats)
		}
	}
	return OutputOperation{}, fmt.Errorf("configured melody %q was not found", name)
}

// StopMelody cancels active host-streamed melody playback.
func (client *Client) StopMelody() bool {
	return client.outputs.StopMelody()
}

// StartStatusLEDEffect begins one asynchronous host-defined LED overlay.
func (client *Client) StartStatusLEDEffect(
	ctx context.Context,
	effect StatusLEDEffect,
) (OutputOperation, error) {
	operation, err := client.outputs.StartStatusEffect(ctx, effect)
	return publicOutputOperation(operation), err
}

// ConfiguredStatusLEDEffects returns the effective named LED-effect catalog.
func (client *Client) ConfiguredStatusLEDEffects() []StatusLEDEffect {
	return appconfig.EffectiveStatusLEDEffects(client.currentHostConfig())
}

// StartConfiguredStatusLEDEffect begins a named effect from the effective catalog.
func (client *Client) StartConfiguredStatusLEDEffect(
	ctx context.Context,
	name string,
) (OutputOperation, error) {
	for _, effect := range client.ConfiguredStatusLEDEffects() {
		if strings.EqualFold(strings.TrimSpace(effect.Name), strings.TrimSpace(name)) {
			return client.StartStatusLEDEffect(ctx, effect)
		}
	}
	return OutputOperation{}, fmt.Errorf(
		"configured status LED effect %q was not found",
		name,
	)
}

// StopStatusLEDEffect cancels the active host-defined LED overlay.
func (client *Client) StopStatusLEDEffect() bool {
	return client.outputs.StopStatusEffect()
}

// ReleaseStatusLEDEffect reconciles board ownership, including after a host
// reconnect where no local retained owner record survived.
func (client *Client) ReleaseStatusLEDEffect(ctx context.Context) error {
	return client.outputs.ReconcileStatusEffect(ctx)
}

// TransmitRF sends a validated 433 MHz code one or more times.
func (client *Client) TransmitRF(
	ctx context.Context,
	code uint32,
	bits, protocol byte,
	pulseUS uint16,
	repeats byte,
) error {
	if repeats == 0 {
		repeats = 1
	}
	if repeats > 20 {
		return fmt.Errorf("RF repeats %d is outside 1..20", repeats)
	}
	payload, err := native.RFTxPayload(code, bits, protocol, pulseUS)
	if err != nil {
		return err
	}
	for repeat := byte(0); repeat < repeats; repeat++ {
		if err := client.runtime.Command(ctx, native.OpRFTx, payload); err != nil {
			return err
		}
	}
	return nil
}

func publicOutputOperation(operation control.StreamOperation) OutputOperation {
	return OutputOperation{
		ID: operation.ID, Kind: operation.Kind,
		Name: operation.Name, Done: operation.Done,
	}
}

// BeginRFLearn starts the bounded timer-learning convenience form.
func (client *Client) BeginRFLearn(ctx context.Context, timeout time.Duration) error {
	_, err := client.runtime.StartRFLearning(ctx, control.RFLearnOptions{
		Mode: control.RFLearnTimer, Timeout: timeout,
	})
	return err
}

// StartRFLearning begins indefinite multi-code or bounded timer learning.
func (client *Client) StartRFLearning(
	ctx context.Context,
	options RFLearnOptions,
) (RFLearnState, error) {
	return client.runtime.StartRFLearning(ctx, options)
}

// RFLearningState returns the latest host-tracked learning lifecycle.
func (client *Client) RFLearningState() RFLearnState {
	return client.runtime.RFLearnState()
}

func (client *Client) ConfigureAutomationAppDispatcher(dispatch func(context.Context, appconfig.AutomationAction) error) {
	client.runtime.SetAutomationAppDispatcher(dispatch)
}

func (client *Client) RFActivity() []Event {
	values := client.runtime.RFActivity()
	result := make([]Event, 0, len(values))
	for _, value := range values {
		result = append(result, publicEvent(value))
	}
	return result
}

func (client *Client) RFReceptions() []control.RFReception { return client.runtime.RFReceptions() }

func (client *Client) AddObservedRF(ctx context.Context, code uint32, bits, protocol byte) error {
	return client.runtime.AddObservedRF(ctx, code, bits, protocol)
}

// RFLastSeen returns genuine board reception time for this exact waveform.
// Zero means not observed in the current host session, not a guessed date.
func (client *Client) RFLastSeen(code uint32, bits, protocol byte) time.Time {
	return client.runtime.RFLastSeen(code, bits, protocol)
}

// CancelRFLearn ends the current learning session with an explicit reason.
func (client *Client) CancelRFLearn(ctx context.Context) error {
	return client.runtime.CancelRFLearning(ctx, "cancelled through API")
}

// RemoveLearnedRF clears one EEPROM-backed learned record by stable slot ID.
func (client *Client) RemoveLearnedRF(ctx context.Context, id byte) error {
	return client.runtime.Command(ctx, native.OpRFLearnRemove, []byte{id})
}

// ClearLearnedRF clears every EEPROM-backed learned RF record.
func (client *Client) ClearLearnedRF(ctx context.Context) error {
	return client.runtime.Command(ctx, native.OpRFLearnClear, nil)
}

// BoardAutomations returns one generation-consistent board-owned rule table.
func (client *Client) BoardAutomations(ctx context.Context) (BoardAutomationSnapshot, error) {
	return control.NewBoardAutomationService(client.runtime).List(ctx)
}

// PutBoardAutomation transactionally adds or edits a rule and verifies its
// exact board-authoritative readback.
func (client *Client) PutBoardAutomation(ctx context.Context, record BoardAutomationRecord) (BoardAutomationReadback, error) {
	return control.NewBoardAutomationService(client.runtime).Put(ctx, record)
}

func (client *Client) RemoveBoardAutomation(ctx context.Context, id byte) error {
	return control.NewBoardAutomationService(client.runtime).Remove(ctx, id)
}

func (client *Client) ClearBoardAutomations(ctx context.Context) error {
	return control.NewBoardAutomationService(client.runtime).Clear(ctx)
}

// MapLearnedRF updates one learned slot while preserving motion safety rules.
func (client *Client) MapLearnedRF(
	ctx context.Context,
	id byte,
	mapping RFMapping,
) error {
	if mapping.Action == RFActionRelay && mapping.Value < 4 {
		return errors.New(
			"learned RF can map directly only to user relays R5..R8; " +
				"use RFActionSide up/down/stop for door-gated motion",
		)
	}
	payload, err := native.RFMappingPayload(
		id,
		byte(mapping.Action),
		mapping.Value,
		byte(mapping.Behavior),
	)
	if err != nil {
		return err
	}
	return control.NewRFReplaceService(client.runtime).UpdateMapping(
		ctx, payload[0], payload[1], payload[2], payload[3],
	)
}

// Snapshot returns cached board state without polling firmware. When no
// transport candidate is cached, serial-reset capability discovery may perform
// one throttled host-side device enumeration.
func (client *Client) Snapshot() Snapshot { return client.snapshot(true) }

// BoardSnapshot is for internal live-state observers. It omits catalogs, macro
// libraries and reset-device enumeration; public query snapshots remain complete.
func (client *Client) BoardSnapshot() Snapshot { return client.snapshot(false) }

func (client *Client) snapshot(includeCatalog bool) Snapshot {
	var snapshot control.Snapshot
	var resetLinesAvailable bool
	var resetLinesPort ports.Info
	var resetLinesReason string
	if includeCatalog {
		snapshot = client.runtime.Snapshot()
		resetLinesAvailable, resetLinesPort, resetLinesReason = client.runtime.ResetLinesCapability()
	} else {
		snapshot = client.runtime.BoardSnapshot()
	}
	// Library snapshots belong to client queries, not the hot board-status
	// path: copying a long take for every internal status check is unnecessary.
	if runner := client.runtime.MacroRunner(); includeCatalog && runner != nil {
		snapshot.Macros = runner.Snapshot()
	}
	client.illuminationMu.RLock()
	illumination := client.illumination
	client.illuminationMu.RUnlock()
	if !snapshot.Connected || !snapshot.HaveSettings || !snapshot.HaveStatus {
		illumination = IlluminationState{}
	}
	var stripEffects []control.StripEffectDescriptor
	if includeCatalog {
		stripEffects = control.SupportedConfiguredStripEffectDescriptors(snapshot.Connected, snapshot.Hello.Capabilities, client.currentStripEffects())
	}
	return Snapshot{
		Connected: snapshot.Connected,
		Paused:    snapshot.Paused,
		Port: PortInfo{
			Name:         snapshot.Port.Name,
			DisplayName:  firstNonempty(snapshot.Port.FriendlyName, snapshot.Port.Product, snapshot.Port.Name),
			VID:          snapshot.Port.VID,
			PID:          snapshot.Port.PID,
			Product:      snapshot.Port.Product,
			Manufacturer: snapshot.Port.Manufacturer,
			SerialNumber: snapshot.Port.SerialNumber,
			FriendlyName: snapshot.Port.FriendlyName,
			InstanceID:   snapshot.Port.InstanceID,
		},
		Hello:                    snapshot.Hello,
		BoardName:                snapshot.BoardName,
		HaveBoardName:            snapshot.HaveBoardName,
		Status:                   snapshot.Status,
		Settings:                 snapshot.Settings,
		HaveStatus:               snapshot.HaveStatus,
		HaveSettings:             snapshot.HaveSettings,
		Programming:              snapshot.Programming,
		StatusUpdated:            snapshot.StatusUpdated,
		ConnectionState:          snapshot.ConnectionState,
		ConnectionReason:         snapshot.ConnectionReason,
		ConnectionUpdated:        snapshot.ConnectionUpdated,
		ConnectionPhase:          snapshot.ConnectionPhase,
		ConnectionAttempt:        snapshot.ConnectionAttempt,
		ConnectionGeneration:     snapshot.ConnectionGeneration,
		ConnectionAttemptStarted: snapshot.ConnectionAttemptStart,
		ConnectionNextRetry:      snapshot.ConnectionNextRetry,
		ConnectionRetryDelayMS:   snapshot.ConnectionRetryDelay.Milliseconds(),
		ConnectionCandidate: PortInfo{
			Name:         snapshot.ConnectionCandidate.Name,
			DisplayName:  firstNonempty(snapshot.ConnectionCandidate.FriendlyName, snapshot.ConnectionCandidate.Product, snapshot.ConnectionCandidate.Name),
			VID:          snapshot.ConnectionCandidate.VID,
			PID:          snapshot.ConnectionCandidate.PID,
			Product:      snapshot.ConnectionCandidate.Product,
			Manufacturer: snapshot.ConnectionCandidate.Manufacturer,
			SerialNumber: snapshot.ConnectionCandidate.SerialNumber,
			FriendlyName: snapshot.ConnectionCandidate.FriendlyName,
			InstanceID:   snapshot.ConnectionCandidate.InstanceID,
		},
		ResetLinesAvailable: resetLinesAvailable,
		ResetLinesPort: PortInfo{
			Name:         resetLinesPort.Name,
			DisplayName:  firstNonempty(resetLinesPort.FriendlyName, resetLinesPort.Product, resetLinesPort.Name),
			VID:          resetLinesPort.VID,
			PID:          resetLinesPort.PID,
			Product:      resetLinesPort.Product,
			Manufacturer: resetLinesPort.Manufacturer,
			SerialNumber: resetLinesPort.SerialNumber,
			FriendlyName: resetLinesPort.FriendlyName,
			InstanceID:   resetLinesPort.InstanceID,
		},
		ResetLinesReason: resetLinesReason,
		ProgramState:     snapshot.ProgramState,
		EmergencyStop:    snapshot.EmergencyStop,
		RFLearning:       snapshot.RFLearning,
		Macros:           snapshot.Macros,
		// The runtime owns the live host configuration used by command execution
		// and by the effect runner. Reuse its canonical catalog here so the public
		// snapshot cannot drift from `effect list` when a new installation receives
		// the editable JSON seed catalog through the effective configuration path.
		Effects:                snapshot.Effects,
		EffectGroups:           snapshot.EffectGroups,
		HardwareProblems:       snapshot.HardwareProblems,
		FrontPanel:             snapshot.FrontPanel,
		HaveFrontPanel:         snapshot.HaveFrontPanel,
		HaveFrontPanelSegments: snapshot.HaveFrontPanelSegments,
		FrontPanelUpdated:      snapshot.FrontPanelUpdated,
		StatusLED:              snapshot.StatusLED,
		HaveStatusLED:          snapshot.HaveStatusLED,
		StatusLEDUpdated:       snapshot.StatusLEDUpdated,
		StatusLEDRevision:      snapshot.StatusLEDRevision,
		PWMValues:              snapshot.PWMValues, PWMRevision: snapshot.PWMRevision, PWMUpdated: snapshot.PWMUpdated,
		PWMRecall:    snapshot.PWMRecall,
		Motion:       snapshot.Motion,
		Outputs:      client.outputs.State(),
		StripEffects: stripEffects,
		Illumination: illumination,
		PortProcess:  snapshot.PortProcess,
	}
}

// Discover scans the local network using DNS-SD/mDNS, SSDP/UPnP,
// WS-Discovery, authenticated-safe UDP broadcast, and optional NetBIOS host
// probing selected by options. Discovery never grants API access.
func (client *Client) Discover(ctx context.Context, options DiscoveryOptions) ([]DiscoveryInstance, error) {
	return discovery.DiscoverWithOptions(ctx, options)
}

// SetSegmentText presents static or scrolling text through the firmware's
// native display path. Text longer than four cells scrolls using dwell as its
// per-window speed; an empty value releases the host segment presentation.
func (client *Client) SetSegmentText(
	ctx context.Context,
	text string,
	dwell time.Duration,
) error {
	if dwell < 0 || dwell > time.Duration(^uint16(0))*time.Millisecond {
		return errors.New("segment dwell must fit 0..65535 milliseconds")
	}
	payload, err := native.DisplayTextPayload(
		native.DisplaySegments,
		uint16(dwell/time.Millisecond),
		text,
	)
	if err != nil {
		return err
	}
	return client.runtime.Command(ctx, native.OpDisplayText, payload)
}

// PresentDisplay sends an arbitrary segment/LCD message through the shared
// primary runtime. Long segment text scrolls automatically; callers can force
// a marquee and select once, explicit loop, or interval scheduling.
func (client *Client) PresentDisplay(
	ctx context.Context,
	request DisplayRequest,
) (DisplayResult, error) {
	return client.runtime.PresentDisplay(ctx, request)
}

// RefreshFrontPanel returns the board's exact cached display/LCD/key state and
// updates Snapshot for every UI consuming the shared primary instance.
func (client *Client) RefreshFrontPanel(ctx context.Context) (FrontPanel, error) {
	return client.runtime.RefreshFrontPanel(ctx)
}

// Events returns the lossy, bounded stream of normalized runtime events.
func (client *Client) Events() <-chan Event {
	return client.events
}

// NextEvent waits for the first matching event newer than afterID.
func (client *Client) NextEvent(
	ctx context.Context,
	afterID uint64,
	kind string,
) (Event, error) {
	event, err := client.runtime.WaitEvent(ctx, afterID, kind)
	if err != nil {
		return Event{}, err
	}
	return publicEvent(event), nil
}

// NextEventStream waits on activity, state, telemetry, or debug without
// allowing a high-rate stream to displace retained activity events.
func (client *Client) NextEventStream(
	ctx context.Context,
	afterID uint64,
	kind string,
	stream string,
) (Event, error) {
	event, err := client.runtime.WaitEventStreamFilter(ctx, afterID, kind, nil, stream)
	if err != nil {
		return Event{}, err
	}
	return publicEvent(event), nil
}

// NextOpcodeEvent waits for an unsolicited raw frame, optionally filtered by
// exact opcode. It is the long-polling counterpart to WebSocket/Socket.IO's
// `opcodes` subscription topic.
func (client *Client) NextOpcodeEvent(
	ctx context.Context,
	afterID uint64,
	kind string,
	opcode *byte,
) (Event, error) {
	event, err := client.runtime.WaitEventFilter(ctx, afterID, kind, opcode)
	if err != nil {
		return Event{}, err
	}
	return publicEvent(event), nil
}

// ExchangeOpcode sends one opaque UART request and waits for the caller's
// expected opcode. The default expectation is ACK, but experimental queries
// can name any response opcode without a host update.
func (client *Client) ExchangeOpcode(
	ctx context.Context,
	opcode byte,
	payload []byte,
	expectedOpcode byte,
) (OpcodeFrame, error) {
	if len(payload) > native.MaxPayload {
		return OpcodeFrame{}, native.ErrPayloadTooLong
	}
	frame, err := client.runtime.Request(ctx, opcode, payload, expectedOpcode)
	if err != nil {
		return OpcodeFrame{}, err
	}
	return OpcodeFrame{
		Opcode: frame.Opcode, Name: native.OpcodeName(frame.Opcode),
		Sequence: frame.Seq, Payload: append([]byte(nil), frame.Payload...),
		PayloadHex: strings.ToUpper(hex.EncodeToString(frame.Payload)),
	}, nil
}

// SendTextMessage validates and routes a typed host, bridge, board, or LCD message.
func (client *Client) SendTextMessage(
	ctx context.Context,
	message TextMessage,
) (Event, error) {
	message.Source = strings.ToLower(strings.TrimSpace(message.Source))
	message.Type = strings.ToLower(strings.TrimSpace(message.Type))
	message.Text = strings.TrimSpace(message.Text)
	message.Action = strings.TrimSpace(message.Action)
	message.Severity = strings.ToLower(strings.TrimSpace(message.Severity))
	message.Correlation = strings.TrimSpace(message.Correlation)
	message.Delivery = strings.ToLower(strings.TrimSpace(message.Delivery))
	if !oneOf(message.Source, "client", "server", "bridge", "board", "lcd", "host", "ipc", "rest", "webhook", "websocket", "socket_io") {
		return Event{}, fmt.Errorf("unsupported message source %q", message.Source)
	}
	if message.Severity == "" {
		message.Severity = "info"
	}
	if !oneOf(message.Severity, "debug", "info", "success", "warning", "error") {
		return Event{}, fmt.Errorf("unsupported message severity %q", message.Severity)
	}
	if message.Delivery == "" {
		message.Delivery = "sync"
	}
	if !oneOf(message.Delivery, "sync", "async") {
		return Event{}, fmt.Errorf("unsupported message delivery %q", message.Delivery)
	}
	if len(message.Correlation) > 96 {
		return Event{}, errors.New("message correlation exceeds 96 characters")
	}
	if message.Type == "" || len(message.Type) > 32 {
		return Event{}, errors.New("message type must contain 1..32 characters")
	}
	for _, character := range message.Type {
		if !(character >= 'a' && character <= 'z') &&
			!(character >= '0' && character <= '9') &&
			!strings.ContainsRune("._-", character) {
			return Event{}, errors.New("message type may contain a-z, 0-9, dot, dash, and underscore")
		}
	}
	if message.Text == "" && message.Line1 == "" && message.Line2 == "" {
		return Event{}, errors.New("message text or LCD lines are required")
	}
	if len(message.Text) > 4096 || len(message.Action) > 512 {
		return Event{}, errors.New("message text/action exceeds protocol limit")
	}
	if len(message.Metadata) > 64 {
		return Event{}, errors.New("message metadata exceeds 64 entries")
	}
	for key, value := range message.Metadata {
		if strings.TrimSpace(key) == "" || len(key) > 64 || len(value) > 1024 {
			return Event{}, errors.New("message metadata keys/values exceed limits")
		}
	}
	event, err := control.SendMessage(ctx, client.runtime, control.Message{
		Source: message.Source, Targets: message.Targets,
		MessageType: message.Type, Text: message.Text,
		Line1: message.Line1, Line2: message.Line2, Action: message.Action,
		Severity: message.Severity, Correlation: message.Correlation, Delivery: message.Delivery,
		Metadata: message.Metadata,
	})
	if err != nil {
		return Event{}, err
	}
	return publicEvent(event), nil
}

func oneOf(value string, allowed ...string) bool {
	for _, candidate := range allowed {
		if value == candidate {
			return true
		}
	}
	return false
}

func splitLCDText(value string) (string, string) {
	value = strings.ReplaceAll(value, "\r", "")
	parts := strings.SplitN(value, "\n", 2)
	if len(parts) == 2 {
		return parts[0], parts[1]
	}
	runes := []rune(value)
	if len(runes) <= 16 {
		return value, ""
	}
	return string(runes[:16]), string(runes[16:])
}

func lcdASCII(value string) string {
	var builder strings.Builder
	for _, character := range value {
		if builder.Len() >= 16 {
			break
		}
		if character < 0x20 || character > 0x7E {
			character = '?'
		}
		builder.WriteRune(character)
	}
	for builder.Len() < 16 {
		builder.WriteByte(' ')
	}
	return builder.String()
}

// LatestEventID returns the most recently published runtime event ID.
func (client *Client) LatestEventID() uint64 {
	return client.runtime.LatestEventID()
}

// EmitHostEvent publishes an integration/lifecycle event without touching the
// serial transport. It is intended for embedders implementing webhooks,
// notifications, or other host-side bridges.
func (client *Client) EmitHostEvent(kind, text string) {
	client.runtime.PublishHostEvent(kind, text)
}

type MediaPlaybackUpdate = control.MediaPlaybackUpdate
type MediaPlaybackSnapshot = control.MediaPlaybackSnapshot
type MediaAuthorityStatus = control.MediaAuthorityStatus

func (client *Client) CheckMediaControlAuthority(ctx context.Context) error {
	return client.runtime.CheckMediaControlAuthority(ctx)
}

type MediaAuthorityRequest = control.MediaAuthorityRequest

func (client *Client) MediaAuthority() MediaAuthorityStatus { return client.runtime.MediaAuthority() }
func (client *Client) ChangeMediaAuthority(value MediaAuthorityRequest) (MediaAuthorityStatus, error) {
	return client.runtime.ChangeMediaAuthority(value)
}

type MediaTimelinePlan = control.MediaTimelinePlan
type MediaTimelineStatus = control.MediaTimelineStatus

func (client *Client) PrepareMediaTimeline(value MediaTimelinePlan) (MediaTimelineStatus, error) {
	return client.runtime.PrepareMediaTimeline(value)
}
func (client *Client) MediaTimeline() MediaTimelineStatus { return client.runtime.MediaTimeline() }

func (client *Client) UpdateMediaPlayback(value MediaPlaybackUpdate) (MediaPlaybackSnapshot, error) {
	return client.runtime.UpdateMediaPlayback(value)
}
func (client *Client) MediaPlayback() MediaPlaybackSnapshot { return client.runtime.MediaPlayback() }

// EmitHostActionEvent publishes a source-tagged host integration event without
// touching the serial transport. Metadata is copied by the runtime.
func (client *Client) EmitHostActionEvent(
	kind, text, source, action string,
	metadata map[string]string,
) Event {
	event := client.runtime.PublishStructuredEvent(control.Event{
		Kind: kind, Text: text, Source: source, Action: action,
		Metadata: metadata,
	})
	return publicEvent(event)
}

// IngestBridgeEvent republishes one authenticated peer event through the
// local runtime without flattening its kind or metadata into a text message.
// The ingress marker prevents bridge cycles while allowing local integrations
// such as the optional PC buzzer mirror to react immediately.
func (client *Client) IngestBridgeEvent(peer string, event Event) Event {
	peer = strings.TrimSpace(peer)
	metadata := cloneStringMap(event.Metadata)
	if metadata == nil {
		metadata = make(map[string]string)
	}
	metadata["bridge.ingress"] = peer
	metadata["bridge.event_id"] = strconv.FormatUint(event.ID, 10)
	if source := strings.TrimSpace(event.Source); source != "" {
		metadata["bridge.original_source"] = source
	}
	forwarded := client.runtime.PublishStructuredEvent(control.Event{
		Kind: event.Kind, Stream: event.Stream, Text: event.Text,
		Frame:     native.Frame{Opcode: event.Opcode, Seq: event.Seq, Payload: append([]byte(nil), event.Payload...)},
		Lifecycle: event.Lifecycle, Reason: event.Reason, State: event.State,
		Gesture: event.Gesture, Source: "bridge", Target: event.Target,
		MessageType: event.MessageType, Action: event.Action, Metadata: metadata,
		RFCode: event.RFCode, RFBits: event.RFBits, RFProtocol: event.RFProtocol,
		RFPulseUS: event.RFPulseUS, ResetCause: event.ResetCause, ResetCount: event.ResetCount,
	})
	return publicEvent(forwarded)
}

// SyncToolchain updates installed cores/libraries and ensures every
// PCController dependency through the controller-owned runner.
// It never opens, resets, or programs a board.
func (client *Client) SyncToolchain(
	ctx context.Context,
	options ToolchainSyncOptions,
	output io.Writer,
) (ToolchainSyncReport, error) {
	if strings.TrimSpace(options.ToolchainCLI) == "" {
		options.ToolchainCLI = client.currentCommandOptions().ArduinoCLI
	}
	return programmer.SyncToolchain(ctx, options, output)
}

// BootstrapToolchain installs one resolved, profile-local firmware toolchain.
// It does not replace an unrelated global dependency installation. Callers may
// supply the latest resolved profile or an intentionally selected rollback lock.
func BootstrapToolchain(
	ctx context.Context,
	options ToolchainBootstrapOptions,
	output io.Writer,
) (ToolchainBootstrapReport, error) {
	return programmer.BootstrapToolchain(ctx, options, output)
}

// LoadToolchainPolicy reads the latest-compatible dependency policy.
func LoadToolchainPolicy(path string) (ToolchainPolicy, error) {
	return programmer.LoadToolchainPolicy(path)
}

// LoadToolchainLock reads an exact, hash-bearing resolved dependency lock.
func LoadToolchainLock(path string) (ToolchainLock, error) {
	return programmer.LoadToolchainLock(path)
}

// ResolveToolchainPolicy resolves stable dependencies without device I/O.
func ResolveToolchainPolicy(
	ctx context.Context,
	policy ToolchainPolicy,
	options ToolchainResolveOptions,
) (ToolchainResolution, error) {
	return programmer.ResolveToolchainPolicy(ctx, policy, options)
}

// CompareToolchainLocks reports substantive changes between exact locks.
func CompareToolchainLocks(current, resolved ToolchainLock) []ToolchainChange {
	return programmer.CompareToolchainLocks(current, resolved)
}

// UpdateToolchainLock atomically writes a changed exact lock without timestamp churn.
func UpdateToolchainLock(path string, current, resolved ToolchainLock) (bool, error) {
	return programmer.UpdateToolchainLock(path, current, resolved)
}

// SetBeforeDisconnectHook lets the primary host bridge release momentary or
// latched PC inputs before an intentional port close removes the UART session.
func (client *Client) SetBeforeDisconnectHook(hook func(string)) {
	client.runtime.SetBeforeDisconnect(hook)
}

// HostSystemStatus returns local OS/network data without touching the serial port.
func (client *Client) HostSystemStatus() (SystemStatus, error) {
	return hostos.Status(ports.EnumerationSource())
}

// PressVirtualKey emits one allowlisted Windows virtual key with a guaranteed release.
func (client *Client) PressVirtualKey(
	ctx context.Context,
	request VirtualKeyRequest,
) (OSActionResult, error) {
	policy := client.currentHostConfig().OSActions.VirtualKeys
	result, err := hostos.DefaultExecutor.PressVirtualKey(ctx, policy, request)
	if err != nil {
		client.EmitHostEvent("os.virtual-key.audit", "Go API denied: "+err.Error())
		return OSActionResult{}, err
	}
	client.EmitHostEvent("os.virtual-key.audit", "Go API "+result.Detail)
	return result, nil
}

// RequestPowerAction invokes a confirmed, allowlisted OS power action.
func (client *Client) RequestPowerAction(
	ctx context.Context,
	request PowerRequest,
) (OSActionResult, error) {
	request.Automation = false
	policy := client.currentHostConfig().OSActions.Power
	result, err := hostos.DefaultExecutor.Power(ctx, policy, request)
	if err != nil {
		client.EmitHostEvent("os.power.audit", "Go API denied: "+err.Error())
		return OSActionResult{}, err
	}
	client.EmitHostEvent("os.power.audit", "Go API "+result.Detail)
	return result, nil
}

// Temperatures lists detected DS18B20 identities, roles, and current readings.
func (client *Client) Temperatures(
	ctx context.Context,
	rescan bool,
) ([]TemperatureSensor, error) {
	var payload []byte
	if rescan {
		payload = []byte{1}
	}
	frame, err := client.runtime.Request(
		ctx,
		native.OpTemperatureList,
		payload,
		native.OpTemperatures,
	)
	if err != nil {
		return nil, err
	}
	return native.ParseTemperatures(frame.Payload)
}

// ListLearned retrieves every learned RF record using bounded pagination.
func (client *Client) ListLearned(ctx context.Context) ([]RFEntry, error) {
	cursor := byte(0)
	var result []RFEntry
	for pageNumber := 0; pageNumber < 86; pageNumber++ {
		frame, err := client.runtime.Request(
			ctx,
			native.OpRFLearnList,
			[]byte{cursor},
			native.OpRFEntries,
		)
		if err != nil {
			return nil, err
		}
		page, err := native.ParseRFEntries(frame.Payload)
		if err != nil {
			return nil, err
		}
		result = append(result, page.Entries...)
		if page.NextCursor == 0xFF {
			return result, nil
		}
		if page.NextCursor == cursor {
			return nil, fmt.Errorf("RF list cursor did not advance from %d", cursor)
		}
		cursor = page.NextCursor
	}
	return nil, fmt.Errorf("RF list exceeded pagination safety limit")
}

// ListLearnedDetailed joins learned records with host names and categories.
func (client *Client) ListLearnedDetailed(ctx context.Context) ([]RFEntryView, error) {
	entries, err := client.ListLearned(ctx)
	if err != nil {
		return nil, err
	}
	sort.Slice(entries, func(i, j int) bool { return entries[i].ID < entries[j].ID })
	config := client.RFPresentation()
	result := make([]RFEntryView, 0, len(entries))
	for _, entry := range entries {
		metadata, _ := config.MetadataFor(appconfig.RFCodeKey{
			Code: entry.Code, Bits: entry.Bits, Protocol: entry.Protocol,
		})
		result = append(result, RFEntryView{
			ID: entry.ID, Code: entry.Code,
			CodeDisplay: appconfig.FormatRFCode(entry.Code, config.DisplayRadix),
			Bits:        entry.Bits, Protocol: entry.Protocol, PulseUS: entry.PulseUS,
			ActionKind: entry.ActionKind, ActionValue: entry.ActionValue,
			Behavior: entry.Behavior, Name: metadata.Name, Category: metadata.Category,
		})
	}
	return result, nil
}

// ListPorts enumerates serial candidates with available USB identity metadata.
func ListPorts() ([]PortInfo, error) {
	list, err := ports.List()
	if err != nil {
		return nil, err
	}
	result := make([]PortInfo, 0, len(list))
	for _, port := range list {
		result = append(result, PortInfo{
			Name:         port.Name,
			DisplayName:  firstNonempty(port.FriendlyName, port.Product, port.Name),
			VID:          port.VID,
			PID:          port.PID,
			Product:      port.Product,
			Manufacturer: port.Manufacturer,
			SerialNumber: port.SerialNumber,
			FriendlyName: port.FriendlyName,
			InstanceID:   port.InstanceID,
		})
	}
	return result, nil
}

func publicPortInfo(info ports.Info) PortInfo {
	return PortInfo{
		Name: info.Name, VID: info.VID, PID: info.PID,
		DisplayName: firstNonempty(info.FriendlyName, info.Product, info.Name),
		Product:     info.Product, Manufacturer: info.Manufacturer,
		SerialNumber: info.SerialNumber,
		FriendlyName: info.FriendlyName,
		InstanceID:   info.InstanceID,
	}
}

func (client *Client) forwardEvents() {
	for {
		var event control.Event
		select {
		case <-client.done:
			close(client.events)
			return
		case event = <-client.runtime.Events():
		}
		forwarded := publicEvent(event)
		select {
		case client.events <- forwarded:
		default:
			select {
			case <-client.events:
			default:
			}
			select {
			case client.events <- forwarded:
			default:
			}
		}
	}
}

func publicEvent(event control.Event) Event {
	forwarded := Event{
		ID: event.ID, Time: event.Time,
		Kind: event.Kind, Stream: event.Stream, Text: event.Text,
		Opcode: event.Frame.Opcode, Seq: event.Frame.Seq,
		Payload:   append([]byte(nil), event.Frame.Payload...),
		Lifecycle: event.Lifecycle,
		Port: PortInfo{
			Name: event.Port.Name, VID: event.Port.VID, PID: event.Port.PID,
			Product: event.Port.Product, Manufacturer: event.Port.Manufacturer,
			SerialNumber: event.Port.SerialNumber,
			FriendlyName: event.Port.FriendlyName,
			InstanceID:   event.Port.InstanceID,
		},
		Reason: event.Reason, State: event.State,
		Gesture: event.Gesture, Source: event.Source,
		Target: event.Target, Targets: append([]string(nil), event.Targets...), MessageType: event.MessageType, Action: event.Action,
		Severity: event.Severity, Correlation: event.Correlation, Delivery: event.Delivery,
		Metadata:    cloneStringMap(event.Metadata),
		Programming: event.Programming,
		RFCode:      event.RFCode, RFBits: event.RFBits,
		RFProtocol: event.RFProtocol, RFPulseUS: event.RFPulseUS,
		ResetCause: event.ResetCause, ResetCount: event.ResetCount,
	}
	if event.HaveRFID {
		id := event.RFID
		forwarded.RFID = &id
	}
	if event.Frame.Opcode == native.OpEvent {
		if parsed, err := native.ParseDeviceEvent(event.Frame.Payload); err == nil {
			forwarded.Device = &parsed
			if parsed.Type == native.EventKey {
				forwarded.Key = parsed.Key + 1
				forwarded.Gesture = control.NormalizeGesture(parsed.Gesture)
				forwarded.Source = map[byte]string{
					native.InputSourcePhysical: "physical",
					native.InputSourceRF:       "rf",
					native.InputSourceHost:     "host",
				}[parsed.Source]
				if parsed.SourceID != 0xFF {
					id := parsed.SourceID
					forwarded.SourceID = &id
				}
			}
			if parsed.Type == native.EventRFLearned {
				id := parsed.RFID
				forwarded.RFID = &id
			}
			if parsed.Type == native.EventRFReceived {
				forwarded.RFCode = parsed.RFCode
				forwarded.RFBits = parsed.RFBits
				forwarded.RFProtocol = parsed.RFProtocol
				forwarded.RFPulseUS = parsed.RFPulseUS
				if parsed.RFLearnedID != 0xFF {
					id := parsed.RFLearnedID
					forwarded.RFID = &id
				}
			}
		}
	}
	return forwarded
}