/* SPDX-License-Identifier: GPL-3.0-only */
/* Local OLED status UI and bounded, direct-API recovery controls. */

#pragma once

#include "esp_err.h"
#include "local_ui_config.h"

#ifdef __cplusplus
extern "C" {
#endif

/*
 * Starts the low-priority status renderer and local recovery controls. The
 * task never becomes a broker client or serial writer. The OLED and buttons
 * are optional, so a missing display is not an error.
 */
esp_err_t local_status_ui_start(const local_ui_config_t *config);

/* Runtime settings are copied atomically and never expose display-frame ownership. */
esp_err_t local_status_ui_get_config(local_ui_config_t *config);
esp_err_t local_status_ui_apply_config(const local_ui_config_t *config);

typedef enum {
    LOCAL_UI_SETTINGS_APPLY, LOCAL_UI_SETTINGS_SAVE, LOCAL_UI_SETTINGS_LOAD,
    LOCAL_UI_SETTINGS_DEFAULTS, LOCAL_UI_SETTINGS_RESET
} local_ui_settings_action_t;

/* Zero-wait RAM projection. Generation is nonzero and never wraps. */
esp_err_t local_status_ui_get_settings(local_ui_config_t *config, uint32_t *generation);
/* Reserve configuration across storage IO, without holding a critical section.
 * Zero expected_generation is for canonical unconditional CLI operations only.
 * Nonzero stale generations return ESP_ERR_INVALID_STATE; contention returns
 * ESP_ERR_TIMEOUT. Load retains the canonical default fallback. Reset commits
 * defaults before publishing RAM, so a storage failure needs no RAM rollback.
 * No display IO occurs here; successful RAM changes signal renderer activity. */
esp_err_t local_status_ui_update_settings(local_ui_settings_action_t action,
    uint32_t expected_generation, const local_ui_config_t *config, bool *loaded_defaults);

/* Preserve a manually selected display diagnostic for a bounded interval. */
void local_status_ui_hold_for_diagnostics(void);

#ifdef __cplusplus
}
#endif