<?php
/**
 * Salyut Agents Settings
 * Uses WordPress Settings API
 */

if ( ! defined( 'ABSPATH' ) ) {
    exit;
}

// Chat widget height ("Custom" mode) bounds. 400px: below this the widget
// feels cramped — barely enough room for the header, one or two message
// bubbles, and the input row without everything scrolling immediately.
// 900px: above this, on an ordinary laptop/desktop viewport the widget
// starts dominating the page rather than sitting as a corner widget, and
// — combined with the separate, always-on viewport-overflow safety rule
// in resources/styles/salyut-agents-frontend.css (min() against 100dvh)
// — a value this high is already well into the range that rule alone
// would clamp on most phones/short screens anyway.
define( 'SALYUT_AGENTS_WIDGET_HEIGHT_MIN_PX', 400 );
define( 'SALYUT_AGENTS_WIDGET_HEIGHT_MAX_PX', 900 );
// Starting value shown the first time an admin switches to "Custom" —
// comfortably inside the bounds above; never used while mode is "default".
define( 'SALYUT_AGENTS_WIDGET_HEIGHT_DEFAULT_PX', 650 );

// ---------------------------------------------------------------------------
// Register settings and fields
// ---------------------------------------------------------------------------

function salyut_agents_register_settings() {

    // ---------------------------------------------------------------------------
    // GENERAL TAB SETTINGS
    // ---------------------------------------------------------------------------

    register_setting(
        'salyut_agents_general_group',
        'salyut_agents_master_enabled',
        [
            'type'              => 'boolean',
            'sanitize_callback' => 'rest_sanitize_boolean',
            'default'           => false,
        ]
    );

    register_setting(
        'salyut_agents_general_group',
        'salyut_agents_delete_data_on_uninstall',
        [
            'type'              => 'boolean',
            'sanitize_callback' => 'rest_sanitize_boolean',
            'default'           => false,
        ]
    );

    register_setting(
        'salyut_agents_general_group',
        'salyut_agents_prompt_response_style',
        [
            'sanitize_callback' => 'salyut_agents_sanitize_text_field_b64',
            'default'           => 'You are having a conversation, not giving a presentation. Respond to what the person just said in one sentence. Then either ask one question if it genuinely moves the conversation forward, or stop — do not default to a question if the visitor has expressed a clear need, pain point, or readiness to move forward; address it directly instead. Never volunteer multiple points unprompted. Never invent or assume features, facts, or capabilities that are not explicitly stated in your instructions. If you do not know the answer to a question, say so honestly and direct the visitor to the appropriate contact or resource.',
        ]
    );

    register_setting(
        'salyut_agents_general_group',
        'salyut_agents_default_model_resolved',
        [
            'type'              => 'string',
            'sanitize_callback' => 'salyut_agents_sanitize_default_model_override',
            'default'           => '',
        ]
    );

    register_setting(
        'salyut_agents_general_group',
        'salyut_agents_chat_disclaimer',
        [
            'type'              => 'string',
            'sanitize_callback' => 'salyut_agents_sanitize_html_field',
            'default'           => salyut_agents_get_default_disclaimer(),
        ]
    );

    register_setting(
        'salyut_agents_general_group',
        'salyut_agents_field_name',
        [
            'sanitize_callback' => 'salyut_agents_sanitize_field_state',
            'default'           => 'optional',
        ]
    );

    register_setting(
        'salyut_agents_general_group',
        'salyut_agents_field_email',
        [
            'sanitize_callback' => 'salyut_agents_sanitize_field_state',
            'default'           => 'optional',
        ]
    );

    register_setting(
        'salyut_agents_general_group',
        'salyut_agents_field_telephone',
        [
            'sanitize_callback' => 'salyut_agents_sanitize_field_state',
            'default'           => 'off',
        ]
    );

    register_setting(
        'salyut_agents_general_group',
        'salyut_agents_newsletter_optin_enabled',
        [
            'type'              => 'boolean',
            'sanitize_callback' => 'rest_sanitize_boolean',
            'default'           => false,
        ]
    );

    register_setting(
        'salyut_agents_general_group',
        'salyut_agents_newsletter_optin_label',
        [
            'type'              => 'string',
            'sanitize_callback' => 'salyut_agents_sanitize_html_field',
            'default'           => __( 'Opt in to our newsletter', 'salyut-agents' ),
        ]
    );

    register_setting(
        'salyut_agents_general_group',
        'salyut_agents_support_email',
        [
            'sanitize_callback' => 'sanitize_email',
            'default'           => '',
        ]
    );

    register_setting(
        'salyut_agents_general_group',
        'salyut_agents_email_notifications',
        [
            'type'              => 'boolean',
            'sanitize_callback' => 'rest_sanitize_boolean',
            'default'           => false,
        ]
    );

    register_setting(
        'salyut_agents_general_group',
        'salyut_agents_notification_email',
        [
            'sanitize_callback' => 'sanitize_email',
            'default'           => '',
        ]
    );

    register_setting(
        'salyut_agents_general_group',
        'salyut_agents_contact_url',
        [
            'sanitize_callback' => 'esc_url_raw',
            'default'           => '',
        ]
    );

    // ---------------------------------------------------------------------------
    // WIDGET BEHAVIOUR SETTINGS
    // ---------------------------------------------------------------------------

    register_setting(
        'salyut_agents_general_group',
        'salyut_agents_start_minimized',
        [
            'type'              => 'boolean',
            'sanitize_callback' => 'rest_sanitize_boolean',
            'default'           => false,
        ]
    );

    register_setting(
        'salyut_agents_general_group',
        'salyut_agents_open_delay',
        [
            'type'              => 'integer',
            'sanitize_callback' => 'absint',
            'default'           => 0,
        ]
    );

    register_setting(
        'salyut_agents_general_group',
        'salyut_agents_scroll_threshold',
        [
            'type'              => 'integer',
            'sanitize_callback' => 'absint',
            'default'           => 0,
        ]
    );

    // ---------------------------------------------------------------------------
    // VISITOR IP DETECTION SETTINGS
    // ---------------------------------------------------------------------------

    // NOTE: these live in salyut_agents_security_group (not salyut_agents_general_group) so
    // they render + save under the Security tab. Keeping them in the general group
    // while rendering them on a separate tab would let each tab's save null out the
    // other tab's options (options.php processes every option in the submitted group).
    register_setting(
        'salyut_agents_security_group',
        'salyut_agents_ip_source',
        [
            'type'              => 'string',
            'sanitize_callback' => 'salyut_agents_sanitize_ip_source',
            'default'           => 'direct',
        ]
    );

    register_setting(
        'salyut_agents_security_group',
        'salyut_agents_ip_custom_header',
        [
            'type'              => 'string',
            'sanitize_callback' => 'salyut_agents_sanitize_ip_custom_header',
            'default'           => '',
        ]
    );

    // ---------------------------------------------------------------------------
    // BOT PROTECTION (TURNSTILE) SETTINGS
    // ---------------------------------------------------------------------------

    register_setting(
        'salyut_agents_security_group',
        'salyut_agents_turnstile_enabled',
        [
            'type'              => 'boolean',
            'sanitize_callback' => 'rest_sanitize_boolean',
            'default'           => false,
        ]
    );

    register_setting(
        'salyut_agents_security_group',
        'salyut_agents_turnstile_site_key',
        [
            'type'              => 'string',
            'sanitize_callback' => 'sanitize_text_field',
            'default'           => '',
        ]
    );

    // Secret key: server-side only. Never localized to JS or returned in any REST
    // response — read exclusively during siteverify in salyut_agents_session().
    register_setting(
        'salyut_agents_security_group',
        'salyut_agents_turnstile_secret_key',
        [
            'type'              => 'string',
            'sanitize_callback' => 'sanitize_text_field',
            'default'           => '',
        ]
    );

    // ---------------------------------------------------------------------------
    // DESIGN TAB SETTINGS
    // ---------------------------------------------------------------------------

    register_setting(
        'salyut_agents_design_group',
        'salyut_agents_primary_color',
        [
            'type'              => 'string',
            'sanitize_callback' => 'sanitize_hex_color',
            'default'           => '',
        ]
    );

    register_setting(
        'salyut_agents_design_group',
        'salyut_agents_accent_color',
        [
            'type'              => 'string',
            'sanitize_callback' => 'sanitize_hex_color',
            'default'           => '',
        ]
    );

    register_setting(
        'salyut_agents_design_group',
        'salyut_agents_header_text_color',
        [
            'sanitize_callback' => 'sanitize_hex_color',
            'default'           => '',
        ]
    );

    register_setting(
        'salyut_agents_design_group',
        'salyut_agents_dept_color',
        [
            'sanitize_callback' => 'sanitize_hex_color',
            'default'           => '#888888',
        ]
    );

    register_setting(
        'salyut_agents_design_group',
        'salyut_agents_bot_bubble_bg',
        [
            'sanitize_callback' => 'sanitize_hex_color',
            'default'           => '',
        ]
    );

    register_setting(
        'salyut_agents_design_group',
        'salyut_agents_bot_bubble_text',
        [
            'sanitize_callback' => 'sanitize_hex_color',
            'default'           => '',
        ]
    );

    register_setting(
        'salyut_agents_design_group',
        'salyut_agents_user_bubble_bg',
        [
            'sanitize_callback' => 'sanitize_hex_color',
            'default'           => '',
        ]
    );

    register_setting(
        'salyut_agents_design_group',
        'salyut_agents_user_bubble_text',
        [
            'sanitize_callback' => 'sanitize_hex_color',
            'default'           => '',
        ]
    );

    register_setting(
        'salyut_agents_design_group',
        'salyut_agents_minimize_btn_color',
        [
            'sanitize_callback' => 'sanitize_hex_color',
            'default'           => '',
        ]
    );

    register_setting(
        'salyut_agents_design_group',
        'salyut_agents_switch_btn_color',
        [
            'sanitize_callback' => 'sanitize_hex_color',
            'default'           => '',
        ]
    );

    register_setting(
        'salyut_agents_design_group',
        'salyut_agents_switch_agent_btn_bg',
        [
            'sanitize_callback' => 'sanitize_hex_color',
            'default'           => '',
        ]
    );

    register_setting(
        'salyut_agents_design_group',
        'salyut_agents_switch_agent_btn_text',
        [
            'sanitize_callback' => 'sanitize_hex_color',
            'default'           => '',
        ]
    );

    register_setting(
        'salyut_agents_design_group',
        'salyut_agents_border_radius',
        [
            'sanitize_callback' => 'absint',
            'default'           => 16,
        ]
    );

    // Widget height — same two-option "mode + companion value" shape as
    // salyut_agents_ip_source/salyut_agents_ip_custom_header above: a mode
    // selector (default/custom) plus the pixel value that only applies
    // when custom is chosen. The pixel value is independently re-clamped
    // on RENDER too (includes/widget.php), not just here on save — a row
    // edited directly in the database (migration, direct SQL, a future
    // import tool) must never be able to push the rendered widget outside
    // [400, 900]px either.
    register_setting(
        'salyut_agents_design_group',
        'salyut_agents_widget_height_mode',
        [
            'type'              => 'string',
            'sanitize_callback' => 'salyut_agents_sanitize_widget_height_mode',
            'default'           => 'default',
        ]
    );

    register_setting(
        'salyut_agents_design_group',
        'salyut_agents_widget_height_px',
        [
            'type'              => 'integer',
            'sanitize_callback' => 'salyut_agents_sanitize_widget_height_px',
            'default'           => SALYUT_AGENTS_WIDGET_HEIGHT_DEFAULT_PX,
        ]
    );

    add_settings_section( 'salyut_agents_general_section',  '', 'salyut_agents_general_section_notice_render', 'salyut-agents-chatbot-general' );
    add_settings_section( 'salyut_agents_leadcap_section',  __( 'Lead Capture', 'salyut-agents' ),    'salyut_agents_section_head_render', 'salyut-agents-chatbot-general' );
    add_settings_section( 'salyut_agents_notify_section',   __( 'Notifications', 'salyut-agents' ),    'salyut_agents_section_head_render', 'salyut-agents-chatbot-general' );
    add_settings_section( 'salyut_agents_behaviour_section',__( 'Widget Behaviour', 'salyut-agents' ), 'salyut_agents_section_head_render', 'salyut-agents-chatbot-general' );
    add_settings_section( 'salyut_agents_data_section',     __( 'Data', 'salyut-agents' ),             'salyut_agents_section_head_render', 'salyut-agents-chatbot-general' );
    add_settings_section( 'salyut_agents_design_section',  '', '__return_false', 'salyut-agents-chatbot-design' );
    // Security tab. The overview section is read-only (no fields) and registered first
    // so it renders above the configurable IP-detection and Turnstile sections.
    add_settings_section( 'salyut_agents_security_overview_section', __( 'Security Overview', 'salyut-agents' ), 'salyut_agents_security_overview_render', 'salyut-agents-chatbot-security' );
    add_settings_section( 'salyut_agents_security_section', __( 'Visitor IP Detection', 'salyut-agents' ), 'salyut_agents_section_head_render', 'salyut-agents-chatbot-security' );
    add_settings_section( 'salyut_agents_turnstile_section', __( 'Bot Protection (Turnstile)', 'salyut-agents' ), 'salyut_agents_section_head_render', 'salyut-agents-chatbot-security' );

    function salyut_agents_section_head_render( $args ) {
        $blurbs = [
            'salyut_agents_leadcap_section'   => __( 'What visitors are asked before a chat begins.', 'salyut-agents' ),
            'salyut_agents_notify_section'    => __( 'Where new-lead alerts are sent.', 'salyut-agents' ),
            'salyut_agents_behaviour_section' => __( 'How and when the widget appears on the page.', 'salyut-agents' ),
            'salyut_agents_data_section'      => __( 'What happens to your stored data if the plugin is deleted.', 'salyut-agents' ),
            'salyut_agents_security_section'  => __( 'How the plugin determines each visitor\'s real IP address for rate limiting.', 'salyut-agents' ),
            'salyut_agents_turnstile_section' => __( 'Optional Cloudflare Turnstile challenge on new chat sessions — the strongest bot gate. Off by default.', 'salyut-agents' ),
        ];
        $id = $args['id'] ?? '';
        if ( ! empty( $blurbs[ $id ] ) ) {
            echo '<p class="description">' . esc_html( $blurbs[ $id ] ) . '</p>';
        }
    }

    // General
    /* translators: %s: product display name */
    add_settings_field( 'salyut_agents_master_enabled',         sprintf( __( '%s Status', 'salyut-agents' ), salyut_agents_display_name() ), 'salyut_agents_master_enabled_render',        'salyut-agents-chatbot-general', 'salyut_agents_general_section' );
    add_settings_field( 'salyut_agents_prompt_response_style',  __( 'Response Style', 'salyut-agents' ),          'salyut_agents_prompt_response_style_render', 'salyut-agents-chatbot-general', 'salyut_agents_general_section' );
    add_settings_field( 'salyut_agents_default_model_resolved',  __( 'Default Model', 'salyut-agents' ),           'salyut_agents_default_model_resolved_render', 'salyut-agents-chatbot-general', 'salyut_agents_general_section' );
    add_settings_field( 'salyut_agents_chat_disclaimer',        __( 'Chatbot Disclaimer', 'salyut-agents' ),      'salyut_agents_chat_disclaimer_render',       'salyut-agents-chatbot-general', 'salyut_agents_general_section' );
    add_settings_field( 'salyut_agents_field_name',      __( 'Name Field', 'salyut-agents' ),      'salyut_agents_field_name_render',      'salyut-agents-chatbot-general', 'salyut_agents_leadcap_section' );
    add_settings_field( 'salyut_agents_field_email',     __( 'Email Field', 'salyut-agents' ),     'salyut_agents_field_email_render',     'salyut-agents-chatbot-general', 'salyut_agents_leadcap_section' );
    add_settings_field( 'salyut_agents_field_telephone', __( 'Telephone Field', 'salyut-agents' ), 'salyut_agents_field_telephone_render', 'salyut-agents-chatbot-general', 'salyut_agents_leadcap_section' );
    add_settings_field( 'salyut_agents_newsletter_optin_enabled', __( 'Newsletter Opt-in', 'salyut-agents' ),       'salyut_agents_newsletter_optin_enabled_render', 'salyut-agents-chatbot-general', 'salyut_agents_leadcap_section' );
    add_settings_field( 'salyut_agents_newsletter_optin_label',   __( 'Newsletter Opt-in Label', 'salyut-agents' ), 'salyut_agents_newsletter_optin_label_render',   'salyut-agents-chatbot-general', 'salyut_agents_leadcap_section' );
    add_settings_field( 'salyut_agents_support_email',          __( 'Support Email', 'salyut-agents' ),           'salyut_agents_support_email_render',         'salyut-agents-chatbot-general', 'salyut_agents_notify_section' );
    add_settings_field( 'salyut_agents_email_notifications', __( 'Lead Email Notifications', 'salyut-agents' ), 'salyut_agents_email_notifications_render', 'salyut-agents-chatbot-general', 'salyut_agents_notify_section' );
    add_settings_field( 'salyut_agents_notification_email',  __( 'Notification Email', 'salyut-agents' ),       'salyut_agents_notification_email_render',  'salyut-agents-chatbot-general', 'salyut_agents_notify_section' );
    add_settings_field( 'salyut_agents_contact_url',            __( 'Contact Page URL', 'salyut-agents' ),        'salyut_agents_contact_url_render',           'salyut-agents-chatbot-general', 'salyut_agents_notify_section' );
    // Widget behaviour
    add_settings_field( 'salyut_agents_start_minimized',        __( 'Start Minimised', 'salyut-agents' ),         'salyut_agents_start_minimized_render',       'salyut-agents-chatbot-general', 'salyut_agents_behaviour_section' );
    add_settings_field( 'salyut_agents_open_delay',             __( 'Auto-open Delay', 'salyut-agents' ),         'salyut_agents_open_delay_render',            'salyut-agents-chatbot-general', 'salyut_agents_behaviour_section' );
    add_settings_field( 'salyut_agents_scroll_threshold',       __( 'Auto-open on Scroll', 'salyut-agents' ),     'salyut_agents_scroll_threshold_render',      'salyut-agents-chatbot-general', 'salyut_agents_behaviour_section' );
    // Data
    add_settings_field( 'salyut_agents_delete_data_on_uninstall', __( 'On Deletion', 'salyut-agents' ),           'salyut_agents_delete_data_on_uninstall_render', 'salyut-agents-chatbot-general', 'salyut_agents_data_section' );
    // Visitor IP detection (Security tab)
    add_settings_field( 'salyut_agents_ip_source',              __( 'CDN / Proxy', 'salyut-agents' ),             'salyut_agents_ip_source_render',             'salyut-agents-chatbot-security', 'salyut_agents_security_section' );
    // Bot protection (Turnstile) (Security tab)
    add_settings_field( 'salyut_agents_turnstile_enabled',      __( 'Enable Turnstile', 'salyut-agents' ),        'salyut_agents_turnstile_enabled_render',     'salyut-agents-chatbot-security', 'salyut_agents_turnstile_section' );
    add_settings_field( 'salyut_agents_turnstile_site_key',     __( 'Site Key', 'salyut-agents' ),                'salyut_agents_turnstile_site_key_render',    'salyut-agents-chatbot-security', 'salyut_agents_turnstile_section' );
    add_settings_field( 'salyut_agents_turnstile_secret_key',   __( 'Secret Key', 'salyut-agents' ),              'salyut_agents_turnstile_secret_key_render',  'salyut-agents-chatbot-security', 'salyut_agents_turnstile_section' );

    // Design Tab
    add_settings_field( 'salyut_agents_primary_color',      __( 'Primary Colour', 'salyut-agents' ),          'salyut_agents_primary_color_render',         'salyut-agents-chatbot-design', 'salyut_agents_design_section' );
    add_settings_field( 'salyut_agents_accent_color',       __( 'Accent Colour', 'salyut-agents' ),           'salyut_agents_accent_color_render',          'salyut-agents-chatbot-design', 'salyut_agents_design_section' );
    add_settings_field( 'salyut_agents_header_text_color',  __( 'Header Text Colour', 'salyut-agents' ),      'salyut_agents_header_text_color_render',     'salyut-agents-chatbot-design', 'salyut_agents_design_section' );
    add_settings_field( 'salyut_agents_dept_color',         __( 'Department Text Colour', 'salyut-agents' ),  'salyut_agents_dept_color_render',            'salyut-agents-chatbot-design', 'salyut_agents_design_section' );
    add_settings_field( 'salyut_agents_minimize_btn_color',    __( 'Minimize Icon', 'salyut-agents' ),              'salyut_agents_minimize_btn_color_render',       'salyut-agents-chatbot-design', 'salyut_agents_design_section' );
    add_settings_field( 'salyut_agents_switch_btn_color',      __( 'Minimize Button Color', 'salyut-agents' ),      'salyut_agents_switch_btn_color_render',         'salyut-agents-chatbot-design', 'salyut_agents_design_section' );
    add_settings_field( 'salyut_agents_switch_agent_btn_bg',   __( 'Switch Agent Button BG', 'salyut-agents' ),     'salyut_agents_switch_agent_btn_bg_render',      'salyut-agents-chatbot-design', 'salyut_agents_design_section' );
    add_settings_field( 'salyut_agents_switch_agent_btn_text', __( 'Switch Agent Button Text', 'salyut-agents' ),   'salyut_agents_switch_agent_btn_text_render',    'salyut-agents-chatbot-design', 'salyut_agents_design_section' );
    add_settings_field( 'salyut_agents_bot_bubble_bg',      __( 'Bot Bubble Background', 'salyut-agents' ),   'salyut_agents_bot_bubble_bg_render',         'salyut-agents-chatbot-design', 'salyut_agents_design_section' );
    add_settings_field( 'salyut_agents_bot_bubble_text',    __( 'Bot Bubble Text', 'salyut-agents' ),         'salyut_agents_bot_bubble_text_render',       'salyut-agents-chatbot-design', 'salyut_agents_design_section' );
    add_settings_field( 'salyut_agents_user_bubble_bg',     __( 'User Bubble Background', 'salyut-agents' ),  'salyut_agents_user_bubble_bg_render',        'salyut-agents-chatbot-design', 'salyut_agents_design_section' );
    add_settings_field( 'salyut_agents_user_bubble_text',   __( 'User Bubble Text', 'salyut-agents' ),        'salyut_agents_user_bubble_text_render',      'salyut-agents-chatbot-design', 'salyut_agents_design_section' );
    add_settings_field( 'salyut_agents_border_radius',      __( 'Widget Corner Radius', 'salyut-agents' ),    'salyut_agents_border_radius_render',         'salyut-agents-chatbot-design', 'salyut_agents_design_section' );
    add_settings_field( 'salyut_agents_widget_height',      __( 'Chat Widget Height', 'salyut-agents' ),      'salyut_agents_widget_height_render',         'salyut-agents-chatbot-design', 'salyut_agents_design_section' );
}
add_action( 'admin_init', 'salyut_agents_register_settings' );

// ---------------------------------------------------------------------------
// Admin notices
// ---------------------------------------------------------------------------

/**
 * Whether an AI provider is connected and usable for text generation.
 *
 * Replaces the old "is the OpenAI API key set" check. Credentials now live in
 * Settings > Connectors (WP core), so we ask the AI Client directly rather than
 * reading a stored key.
 *
 * @return bool
 */
function salyut_agents_ai_is_available(): bool {
    if ( ! function_exists( 'wp_ai_client_prompt' ) ) {
        return false;
    }

    return (bool) wp_ai_client_prompt( 'test' )->is_supported_for_text_generation();
}

add_action( 'admin_notices', 'salyut_agents_configuration_notices', 25 );

function salyut_agents_configuration_notices(): void {
    if ( ! current_user_can( 'manage_options' ) ) {
        return;
    }

    $screen = get_current_screen();
    if ( ! $screen ) {
        return;
    }
    

    $master_enabled = (bool) get_option( 'salyut_agents_master_enabled', false );
    $ai_available   = salyut_agents_ai_is_available();
    $settings_url   = admin_url( 'edit.php?post_type=salyut_lead&page=salyut-agents-settings' );
    $connectors_url = admin_url( 'options-connectors.php' );
    $display_name   = salyut_agents_display_name();

    $is_salyut_agents_page = (
        $screen->post_type === 'salyut_lead' ||
        $screen->post_type === 'salyut_agent' ||
        strpos( $screen->id, 'salyut' ) !== false
    );

    // Show globally when the chatbot is on but something is broken
    $is_broken = $master_enabled && ! $ai_available;

    if ( ! $is_salyut_agents_page && ! $is_broken ) {
        return;
    }

    $notices = [];

    if ( ! $ai_available ) {
        $notices[] = [
            'type'    => 'error',
            'message' => sprintf(
                /* translators: 1: product display name, 2: Connectors settings URL */
                __( '<strong>%1$s:</strong> No AI provider connected. The chatbot will not work until you connect a provider in <a href="%2$s">Settings &rsaquo; Connectors</a>.', 'salyut-agents' ),
                $display_name,
                esc_url( $connectors_url )
            ),
        ];
    }

    if ( $is_salyut_agents_page && ! $master_enabled ) {
        $notices[] = [
            'type'    => 'warning',
            'message' => sprintf(
                /* translators: 1: product display name, 2: settings page URL, 3: product display name */
                __( '<strong>%1$s is currently disabled</strong> and will not appear anywhere on your website. <a href="%2$s">Enable %3$s</a>', 'salyut-agents' ),
                $display_name,
                esc_url( $settings_url ),
                $display_name
            ),
        ];
    }

    if ( $is_salyut_agents_page && $master_enabled && ! salyut_agents_has_active_prompt() ) {
        $agents_url = admin_url( 'edit.php?post_type=salyut_agent' );
        $notices[] = [
            'type'    => 'warning',
            'message' => sprintf(
                /* translators: 1: product display name, 2: agents page URL */
                __( '<strong>%1$s:</strong> The chatbot is enabled but has no agents configured. <a href="%2$s">Add an agent</a>.', 'salyut-agents' ),
                $display_name,
                esc_url( $agents_url )
            ),
        ];
    }

    if ( $is_salyut_agents_page &&
         get_option( 'salyut_agents_field_name',      'optional' ) === 'off' &&
         get_option( 'salyut_agents_field_email',     'optional' ) === 'off' &&
         get_option( 'salyut_agents_field_telephone', 'off' )     === 'off'
    ) {
        $notices[] = [
            'type'    => 'warning',
            'message' => __( 'No lead capture fields selected. The chatbot will start immediately without collecting information upfront.', 'salyut-agents' ),
        ];
    }

    if ( $is_salyut_agents_page && ! get_option( 'salyut_agents_default_agent_id', 0 ) ) {
        $agents_url = admin_url( 'edit.php?post_type=salyut_agent' );
        $notices[] = [
            'type'    => 'warning',
            'message' => sprintf(
                /* translators: 1: product display name, 2: agents page URL */
                __( '<strong>%1$s:</strong> No default agent assigned. The chatbot will not appear on any page that does not have a specific agent assigned. <a href="%2$s">Assign a default agent</a>.', 'salyut-agents' ),
                $display_name,
                esc_url( $agents_url )
            ),
        ];
    }

    foreach ( $notices as $notice ) {
        printf(
            '<div class="notice notice-%s"><p>%s</p></div>',
            esc_attr( $notice['type'] ),
            wp_kses( $notice['message'], [ 'strong' => [], 'a' => [ 'href' => [] ] ] )
        );
    }

    if ( $is_salyut_agents_page ) {
        salyut_agents_render_provider_connection_notice( $display_name );
    }
}

/**
 * A short, human reason for one agent's recorded issue, for the provider
 * connection notice. Never guesses provider-specific detail beyond the AI
 * Client's own error code and HTTP status.
 *
 * @param array  $issue       One entry from salyut_agents_get_agent_model_issues(),
 *                             or [] if the agent only appears in the cached
 *                             disconnected-models list (no issue recorded yet
 *                             from an actual attempt).
 * @param array  $models      salyut_agents_get_available_models().
 * @return string
 */
function salyut_agents_describe_model_issue( array $issue, array $models ): string {
    if ( empty( $issue ) ) {
        return __( 'provider not connected', 'salyut-agents' );
    }

    if ( 'mismatch' === ( $issue['type'] ?? '' ) ) {
        $actual_label = $models[ $issue['actual_model'] ?? '' ]['label'] ?? ( $issue['actual_model'] ?? '' );
        return sprintf(
            /* translators: %s: the model label that actually answered */
            __( 'replied from %s instead of the selected model — unexpected, please check', 'salyut-agents' ),
            $actual_label
        );
    }

    $error_class = (string) ( $issue['error_class'] ?? '' );

    if ( 'provider_not_connected' === $error_class ) {
        return __( 'provider not connected', 'salyut-agents' );
    }

    if ( 'model_resolution_error' === $error_class ) {
        return __( 'the model could not be resolved', 'salyut-agents' );
    }

    if ( false !== strpos( $error_class, '(401)' ) || false !== strpos( $error_class, '(403)' ) ) {
        return __( 'the provider rejected the credentials', 'salyut-agents' );
    }

    if ( false !== strpos( $error_class, '(429)' ) ) {
        return __( 'the provider’s quota or rate limit was reached', 'salyut-agents' );
    }

    if ( false !== strpos( $error_class, '(402)' ) ) {
        return __( 'a payment issue with the provider', 'salyut-agents' );
    }

    // Point 4c: a transient class means the provider itself never actually
    // answered with an error — it simply didn't answer in time (a timeout,
    // a network error, an "overloaded"/5xx status, or a response that ran
    // out of budget before producing content) — distinct wording from a
    // hard failure the provider genuinely rejected.
    if ( salyut_agents_is_transient_issue_class( $error_class ) ) {
        return __( 'did not answer in time — may already be working again', 'salyut-agents' );
    }

    return __( 'the provider returned an error', 'salyut-agents' );
}

/**
 * Dismissible warning, shown only on this plugin's own admin screens, listing
 * every agent (and the default agent) that is not answering because its
 * selected model's provider is not connected, or whose last attempt failed
 * for some other reason (an invalid key, an exhausted quota, a payment
 * failure, etc.) — one line per agent, with its last recorded reason.
 *
 * Dismissal is remembered per user against the current set of problems (see
 * salyut_agents_provider_notice_signature()) — fixing or changing what is
 * wrong brings the notice back even if a user already dismissed an older
 * version of it.
 *
 * @param string $display_name
 */
function salyut_agents_render_provider_connection_notice( string $display_name ): void {
    $disconnected = salyut_agents_get_disconnected_agent_models();
    // Point 4b: already drops any transient issue past its TTL — the
    // provider may simply be working again, and this notice should not
    // keep claiming otherwise forever.
    $issues       = salyut_agents_get_live_model_issues();

    if ( empty( $disconnected ) && empty( $issues ) ) {
        return;
    }

    $signature = salyut_agents_provider_notice_signature( $disconnected, $issues );
    $dismissed = get_user_meta( get_current_user_id(), 'salyut_agents_provider_notice_dismissed', true );

    if ( $dismissed === $signature ) {
        return;
    }

    $models         = salyut_agents_get_available_models();
    $connectors_url = admin_url( 'options-connectors.php' );

    // Merge the cached (dropdown-marking) list with the per-agent issues
    // record into one row per affected agent, keyed by agent ID. An agent
    // with a real recorded issue takes that over the cached list's generic
    // "provider not connected" guess, since it reflects an actual attempt.
    $rows = [];

    foreach ( $disconnected as $item ) {
        $rows[ $item['agent_id'] ] = [
            'agent_title'      => $item['agent_title'],
            'model_id'         => $item['model_id'],
            'model_label'      => $models[ $item['model_id'] ]['label'] ?? $item['model_id'],
            'is_default_agent' => $item['is_default_agent'],
            'issue'            => [],
        ];
    }

    foreach ( $issues as $agent_id => $issue ) {
        $agent_id    = (int) $agent_id;
        $agent_title = get_the_title( $agent_id );
        $model_id    = $issue['model'] ?? $issue['requested_model'] ?? '';

        if ( '' === $agent_title ) {
            $agent_title = __( '(unknown agent)', 'salyut-agents' );
        }

        $rows[ $agent_id ] = [
            'agent_title'      => $agent_title,
            'model_id'         => $model_id,
            'model_label'      => $models[ $model_id ]['label'] ?? $model_id,
            'is_default_agent' => $agent_id === (int) get_option( 'salyut_agents_default_agent_id', 0 ),
            'issue'            => $issue,
        ];
    }

    // Point 4d: one last live try per agent, before ever showing the
    // banner — a provider that has simply come back clears itself here
    // instead of waiting for the next real visitor message.
    foreach ( $rows as $agent_id => $row ) {
        if ( '' === $row['model_id'] ) {
            continue;
        }
        $model_config = salyut_agents_get_model_config( $row['model_id'] );
        if ( ! $model_config ) {
            continue;
        }
        if ( salyut_agents_maybe_quick_recheck_agent( $agent_id, $row['model_id'], $model_config ) ) {
            unset( $rows[ $agent_id ] );
        }
    }

    if ( empty( $rows ) ) {
        return;
    }

    echo '<div class="notice notice-warning">';

    printf(
        '<p><strong>%s</strong></p>',
        esc_html(
            sprintf(
                /* translators: %s: product display name */
                __( '%s: the agents below are not answering until this is fixed.', 'salyut-agents' ),
                $display_name
            )
        )
    );

    echo '<ul style="margin-left:1.2em;list-style:disc;">';
    foreach ( $rows as $agent_id => $row ) {
        $edit_link = get_edit_post_link( $agent_id, 'raw' );
        $reason    = salyut_agents_describe_model_issue( $row['issue'], $models );

        printf(
            '<li>%s</li>',
            wp_kses(
                $row['is_default_agent']
                    ? sprintf(
                        /* translators: 1: agent edit URL, 2: agent name, 3: model label, 4: reason */
                        __( '<a href="%1$s">%2$s</a> (default agent) — <strong>%3$s</strong>: %4$s.', 'salyut-agents' ),
                        esc_url( $edit_link ? $edit_link : '' ),
                        esc_html( $row['agent_title'] ),
                        esc_html( $row['model_label'] ),
                        esc_html( $reason )
                    )
                    : sprintf(
                        /* translators: 1: agent edit URL, 2: agent name, 3: model label, 4: reason */
                        __( '<a href="%1$s">%2$s</a> — <strong>%3$s</strong>: %4$s.', 'salyut-agents' ),
                        esc_url( $edit_link ? $edit_link : '' ),
                        esc_html( $row['agent_title'] ),
                        esc_html( $row['model_label'] ),
                        esc_html( $reason )
                    ),
                [ 'strong' => [], 'a' => [ 'href' => [] ] ]
            )
        );
    }
    echo '</ul>';

    printf(
        '<p><a href="%1$s">%2$s</a> &middot; <a href="%3$s">%4$s</a></p>',
        esc_url( $connectors_url ),
        esc_html__( 'Connect a provider', 'salyut-agents' ),
        esc_url( wp_nonce_url( add_query_arg( 'salyut_agents_dismiss_provider_notice', '1' ), 'salyut_agents_dismiss_provider_notice' ) ),
        esc_html__( 'Dismiss', 'salyut-agents' )
    );

    echo '</div>';
}

function salyut_agents_has_active_prompt(): bool {
    // Configured == at least one published agent exists.
    $agents = get_posts( [
        'post_type'      => 'salyut_agent',
        'post_status'    => 'publish',
        'posts_per_page' => 1,
        'fields'         => 'ids',
        'no_found_rows'  => true,
    ] );

    return ! empty( $agents );
}

// ---------------------------------------------------------------------------
// Field render callbacks
// ---------------------------------------------------------------------------

function salyut_agents_master_enabled_render() {
    $enabled = get_option( 'salyut_agents_master_enabled', false );
    ?>
    <p class="description"><?php echo esc_html__( 'The go-live switch. Off by default: your agents and settings are saved, but the chat appears nowhere on your site until you turn this on. Turning it off again hides the chat everywhere without touching your configuration.', 'salyut-agents' ); ?></p>
    <label class="salyut-agents-toggle">
        <input type="checkbox"
               name="salyut_agents_master_enabled"
               value="1"
               class="salyut-agents-toggle__input"
               <?php checked( $enabled, true ); ?> />
        <span class="salyut-agents-toggle__switch"></span>
        <span class="salyut-agents-toggle__label">
            <?php echo $enabled ? esc_html__( 'Enabled', 'salyut-agents' ) : esc_html__( 'Disabled', 'salyut-agents' ); ?>
        </span>
    </label>
    <?php
}

/**
 * The model a brand-new agent starts with. Viewing this field is what
 * resolves it in the first place on an install that has never needed one
 * yet (salyut_agents_get_default_model() resolves-and-stores on its first
 * ever call, same as any other call site — see models-config.php) — the
 * owner lands on a real, concrete value rather than a blank one, and can
 * change it immediately, same picker as the agent editor's own model field.
 */
function salyut_agents_default_model_resolved_render() {
    $current           = salyut_agents_get_default_model();
    $selectable_models = salyut_agents_get_selectable_models( $current );

    $provider_labels = [
        'openai'    => 'OpenAI',
        'anthropic' => 'Anthropic',
        'google'    => 'Google',
    ];
    $provider_label = fn( string $p ): string => $provider_labels[ $p ] ?? ucfirst( $p );

    $models_by_provider = [];
    foreach ( $selectable_models as $model_id => $model ) {
        $provider = $model['provider'] ?? 'other';
        $models_by_provider[ $provider ][ $model_id ] = $model;
    }
    ?>
    <select name="salyut_agents_default_model_resolved" id="salyut_agents_default_model_resolved">
        <?php foreach ( $models_by_provider as $provider => $group ) : ?>
            <optgroup label="<?php echo esc_attr( $provider_label( (string) $provider ) ); ?>">
                <?php foreach ( $group as $model_id => $model ) : ?>
                    <?php
                    $option_label = ( ! empty( $model['is_recommended'] ) ? '⭐ ' : '' ) . $model['label'];
                    if ( ! salyut_agents_is_model_provider_connected( $model_id ) ) {
                        $option_label .= ' ' . __( '(provider not connected)', 'salyut-agents' );
                    }
                    ?>
                    <option value="<?php echo esc_attr( $model_id ); ?>" <?php selected( $current, $model_id ); ?>>
                        <?php echo esc_html( $option_label ); ?>
                    </option>
                <?php endforeach; ?>
            </optgroup>
        <?php endforeach; ?>
    </select>
    <p class="description">
        <?php esc_html_e( 'The model a brand-new agent starts with. Resolved automatically to a connected provider the first time it was needed — change it here if you would rather a different one.', 'salyut-agents' ); ?>
    </p>
    <?php
}

function salyut_agents_delete_data_on_uninstall_render() {
    $delete       = get_option( 'salyut_agents_delete_data_on_uninstall', false );
    $display_name = salyut_agents_display_name();
    ?>
    <label style="display:flex;align-items:flex-start;gap:8px;">
        <input type="checkbox"
               name="salyut_agents_delete_data_on_uninstall"
               value="1"
               <?php checked( $delete ); ?>
               style="margin-top:3px;" />
        <span>
            <?php
            printf(
                /* translators: %s: product display name */
                esc_html__( 'Delete all %s data when the plugin is deleted (leads, conversations, agents, and settings). Off by default — if you reinstall, your data will be exactly as you left it.', 'salyut-agents' ),
                esc_html( $display_name )
            );
            ?>
        </span>
    </label>
    <?php
}

/**
 * Prominent, non-dismissible "before you go live" notice at the top of the
 * General tab (above the go-live switch). Plain in-plugin disclosure — it
 * replaced a blocking Terms-of-Service acceptance checkbox. It states the
 * admin's responsibilities but gates nothing; the plugin works without it.
 */
function salyut_agents_general_section_notice_render() {
    $name = salyut_agents_display_name();
    ?>
    <div class="notice notice-warning inline" style="max-width:48em;margin:1em 0;padding:10px 14px;">
        <p style="margin:0 0 .5em;"><strong><?php esc_html_e( 'Before you go live — your responsibilities', 'salyut-agents' ); ?></strong></p>
        <p style="margin:.5em 0;">
            <?php
            /* translators: %s: product display name */
            printf( esc_html__( '%s sends visitor conversations to the AI provider you connect (Anthropic, Google, or OpenAI) using your own account. By using the plugin you accept the following.', 'salyut-agents' ), esc_html( $name ) );
            ?>
        </p>
        <ul style="list-style:disc;margin:.5em 0 .5em 1.4em;">
            <li>
                <strong><?php esc_html_e( 'Costs are yours.', 'salyut-agents' ); ?></strong>
                <?php
                /* translators: %s: product display name */
                printf( esc_html__( 'Your AI provider bills you directly for every message at their rates — %s adds no charges and imposes no limits. Usage rises with traffic and can spike under abuse. Set a hard spending cap in your provider’s dashboard before going live. The built-in honeypot, timing checks, rate limiting, and optional Turnstile reduce abuse but do not replace a provider spend cap.', 'salyut-agents' ), esc_html( $name ) );
                ?>
            </li>
            <li>
                <strong><?php esc_html_e( 'Acceptable use.', 'salyut-agents' ); ?></strong>
                <?php
                /* translators: %s: product display name */
                printf( esc_html__( 'Do not use %s for any illegal, harmful, deceptive, or abusive purpose, and follow your AI provider’s usage policies. You are responsible for what you instruct your agents to do and say.', 'salyut-agents' ), esc_html( $name ) );
                ?>
            </li>
            <li>
                <strong><?php esc_html_e( 'No warranty.', 'salyut-agents' ); ?></strong>
                <?php
                /* translators: %s: product display name */
                printf( esc_html__( '%s is free software provided under the GPL with no warranty of any kind. AI replies can be inaccurate — review them. You are responsible for your website’s legal compliance, including privacy notices, disclosures, and how visitor data is handled.', 'salyut-agents' ), esc_html( $name ) );
                ?>
            </li>
        </ul>
        <p style="margin:.5em 0 0;">
            <?php
            printf(
                wp_kses(
                    /* translators: 1: Terms of Service URL, 2: product display name */
                    __( 'Full terms (informational, not required to use the plugin): <a href="%1$s" target="_blank" rel="noopener noreferrer">%2$s Terms of Service</a>.', 'salyut-agents' ),
                    [ 'a' => [ 'href' => [], 'target' => [], 'rel' => [] ] ]
                ),
                'https://salyutplugins.com/terms-of-service',
                esc_html( $name )
            );
            ?>
        </p>
    </div>
    <?php
}

function salyut_agents_prompt_response_style_render() {
    $raw     = get_option( 'salyut_agents_prompt_response_style', '' );
    $decoded = base64_decode( $raw, true );
    $content = ( $decoded !== false && base64_encode( $decoded ) === $raw ) ? $decoded : $raw;
    ?>
    <textarea name="salyut_agents_prompt_response_style"
              id="salyut_agents_prompt_response_style"
              rows="4"
              class="large-text code"><?php echo esc_textarea( $content ); ?></textarea>
    <p class="description">
        <?php esc_html_e( 'Controls how the chatbot delivers responses. The default keeps replies to one sentence, then asks a follow-up question only if it genuinely moves the conversation forward — if the visitor has signalled a clear need or readiness to act, it addresses that directly instead of deflecting with a question. The response-length ceiling is tuned per model and can be overridden per agent under Advanced. Only change this if your use case requires a different delivery style.', 'salyut-agents' ); ?>
    </p>
    <?php
}

function salyut_agents_primary_color_render() {
    $color = get_option( 'salyut_agents_primary_color', '' );
    ?>
    <p class="description"><?php echo esc_html__( 'Main brand colour — used for the chat header background and input focus ring.', 'salyut-agents' ); ?></p>
    <input type="text"
           name="salyut_agents_primary_color"
           id="salyut_agents_primary_color"
           value="<?php echo esc_attr( $color ); ?>"
           class="salyut-agents-color-picker"
           data-default-color="" />
    <?php
}

function salyut_agents_accent_color_render() {
    $color = get_option( 'salyut_agents_accent_color', '' );
    ?>
    <p class="description"><?php echo esc_html__( 'Accent colour — used for the send button and interactive highlights.', 'salyut-agents' ); ?></p>
    <input type="text"
           name="salyut_agents_accent_color"
           id="salyut_agents_accent_color"
           value="<?php echo esc_attr( $color ); ?>"
           class="salyut-agents-color-picker"
           data-default-color="" />
    <?php
}

function salyut_agents_get_default_disclaimer() {
    return __( 'AI may be inaccurate. Use at your own risk. By using this chat, you agree to our <a href="/terms-conditions">Terms and Conditions.</a>', 'salyut-agents' );
}

function salyut_agents_chat_disclaimer_render() {
    $raw     = get_option( 'salyut_agents_chat_disclaimer', salyut_agents_get_default_disclaimer() );
    $decoded = base64_decode( $raw, true );
    $content = ( $decoded !== false && base64_encode( $decoded ) === $raw ) ? $decoded : $raw;
    ?>
    <p class="description"><?php echo esc_html__( 'Optional disclaimer shown beneath the chatbot. Supports links and basic formatting.', 'salyut-agents' ); ?></p>
    <?php
    wp_editor(
        $content,
        'salyut_agents_chat_disclaimer',
        [
            'textarea_name' => 'salyut_agents_chat_disclaimer',
            'textarea_rows' => 5,
            'media_buttons' => false,
            'teeny'         => true,
            'quicktags'     => true,
        ]
    );
}

function salyut_agents_field_name_render() {
    $value = get_option( 'salyut_agents_field_name', 'optional' );
    ?>
    <p class="description"><?php echo esc_html__( 'Controls whether the Name field appears in the pre-chat form, and whether visitors must fill it in before starting a chat.', 'salyut-agents' ); ?></p>
    <label style="margin-right:16px;">
        <input type="radio" name="salyut_agents_field_name" value="off" <?php checked( $value, 'off' ); ?> />
        <?php esc_html_e( 'Off', 'salyut-agents' ); ?>
    </label>
    <label style="margin-right:16px;">
        <input type="radio" name="salyut_agents_field_name" value="optional" <?php checked( $value, 'optional' ); ?> />
        <?php esc_html_e( 'Optional', 'salyut-agents' ); ?>
    </label>
    <label>
        <input type="radio" name="salyut_agents_field_name" value="required" <?php checked( $value, 'required' ); ?> />
        <?php esc_html_e( 'Required', 'salyut-agents' ); ?>
    </label>
    <?php
}

function salyut_agents_field_email_render() {
    $value = get_option( 'salyut_agents_field_email', 'optional' );
    ?>
    <p class="description"><?php echo esc_html__( 'Controls whether the Email field appears in the pre-chat form, and whether visitors must fill it in before starting a chat.', 'salyut-agents' ); ?></p>
    <label style="margin-right:16px;">
        <input type="radio" name="salyut_agents_field_email" value="off" <?php checked( $value, 'off' ); ?> />
        <?php esc_html_e( 'Off', 'salyut-agents' ); ?>
    </label>
    <label style="margin-right:16px;">
        <input type="radio" name="salyut_agents_field_email" value="optional" <?php checked( $value, 'optional' ); ?> />
        <?php esc_html_e( 'Optional', 'salyut-agents' ); ?>
    </label>
    <label>
        <input type="radio" name="salyut_agents_field_email" value="required" <?php checked( $value, 'required' ); ?> />
        <?php esc_html_e( 'Required', 'salyut-agents' ); ?>
    </label>
    <?php
}

function salyut_agents_field_telephone_render() {
    $value = get_option( 'salyut_agents_field_telephone', 'off' );
    ?>
    <p class="description"><?php echo esc_html__( 'Controls whether the Telephone field appears in the pre-chat form, and whether visitors must fill it in before starting a chat.', 'salyut-agents' ); ?></p>
    <label style="margin-right:16px;">
        <input type="radio" name="salyut_agents_field_telephone" value="off" <?php checked( $value, 'off' ); ?> />
        <?php esc_html_e( 'Off', 'salyut-agents' ); ?>
    </label>
    <label style="margin-right:16px;">
        <input type="radio" name="salyut_agents_field_telephone" value="optional" <?php checked( $value, 'optional' ); ?> />
        <?php esc_html_e( 'Optional', 'salyut-agents' ); ?>
    </label>
    <label>
        <input type="radio" name="salyut_agents_field_telephone" value="required" <?php checked( $value, 'required' ); ?> />
        <?php esc_html_e( 'Required', 'salyut-agents' ); ?>
    </label>
    <?php
}

function salyut_agents_newsletter_optin_enabled_render() {
    $enabled = (bool) get_option( 'salyut_agents_newsletter_optin_enabled', false );
    ?>
    <p class="description"><?php echo esc_html__( 'When enabled, a newsletter opt-in checkbox appears at the bottom of the pre-chat form. Requires at least one lead field to be active.', 'salyut-agents' ); ?></p>
    <label class="salyut-agents-toggle">
        <input type="checkbox"
               name="salyut_agents_newsletter_optin_enabled"
               value="1"
               class="salyut-agents-toggle__input"
               <?php checked( $enabled, true ); ?> />
        <span class="salyut-agents-toggle__switch"></span>
        <span class="salyut-agents-toggle__label">
            <?php echo $enabled ? esc_html__( 'Enabled', 'salyut-agents' ) : esc_html__( 'Disabled', 'salyut-agents' ); ?>
        </span>
    </label>
    <?php
}

function salyut_agents_newsletter_optin_label_render() {
    $raw     = get_option( 'salyut_agents_newsletter_optin_label', __( 'Opt in to our newsletter', 'salyut-agents' ) );
    $decoded = base64_decode( $raw, true );
    $content = ( $decoded !== false && base64_encode( $decoded ) === $raw ) ? $decoded : $raw;
    ?>
    <p class="description"><?php echo esc_html__( 'Label shown next to the opt-in checkbox. Supports links — e.g. you can link to your newsletter sign-up page. Only displayed when Newsletter Opt-in is enabled above.', 'salyut-agents' ); ?></p>
    <?php
    wp_editor(
        $content,
        'salyut_agents_newsletter_optin_label',
        [
            'textarea_name' => 'salyut_agents_newsletter_optin_label',
            'textarea_rows' => 3,
            'media_buttons' => false,
            'teeny'         => true,
            'quicktags'     => true,
        ]
    );
}

function salyut_agents_support_email_render() {
    $email = get_option( 'salyut_agents_support_email', '' );
    ?>
    <p class="description"><?php echo esc_html__( 'Shown to users when their session hits a limit or something goes wrong.', 'salyut-agents' ); ?></p>
    <input type="email"
           name="salyut_agents_support_email"
           value="<?php echo esc_attr( $email ); ?>"
           class="regular-text"
           placeholder="hello@yoursite.com" />
    <?php
}

function salyut_agents_email_notifications_render() {
    $enabled = (bool) get_option( 'salyut_agents_email_notifications', false );
    ?>
    <p class="description"><?php echo esc_html__( 'Off by default. When enabled, a daily digest email is sent to the site administrator summarising new leads. Only sends on days where new leads have come in since the last email.', 'salyut-agents' ); ?></p>
    <label class="salyut-agents-toggle">
        <input type="checkbox"
               name="salyut_agents_email_notifications"
               value="1"
               class="salyut-agents-toggle__input"
               <?php checked( $enabled, true ); ?> />
        <span class="salyut-agents-toggle__switch"></span>
        <span class="salyut-agents-toggle__label">
            <?php echo $enabled ? esc_html__( 'Enabled', 'salyut-agents' ) : esc_html__( 'Disabled', 'salyut-agents' ); ?>
        </span>
    </label>
    <?php
}

function salyut_agents_notification_email_render() {
    $email = get_option( 'salyut_agents_notification_email', '' );
    ?>
    <p class="description"><?php echo esc_html__( 'Email address to receive the daily lead digest. Defaults to the WordPress admin email if left blank.', 'salyut-agents' ); ?></p>
    <input type="email"
           name="salyut_agents_notification_email"
           value="<?php echo esc_attr( $email ); ?>"
           class="regular-text"
           placeholder="<?php echo esc_attr( get_option( 'admin_email' ) ); ?>" />
    <?php
}

function salyut_agents_contact_url_render() {
    $url = get_option( 'salyut_agents_contact_url', '' );
    ?>
    <p class="description"><?php echo esc_html__( 'Optional contact page link shown alongside the support email.', 'salyut-agents' ); ?></p>
    <input type="url"
           name="salyut_agents_contact_url"
           value="<?php echo esc_attr( $url ); ?>"
           class="regular-text"
           placeholder="https://yoursite.com/contact" />
    <?php
}

// ---------------------------------------------------------------------------
// Widget behaviour field render callbacks
// ---------------------------------------------------------------------------

function salyut_agents_start_minimized_render() {
    $enabled = (bool) get_option( 'salyut_agents_start_minimized', false );
    ?>
    <p class="description"><?php echo esc_html__( 'When enabled, the chat widget loads collapsed on every page. Visitors can open it manually, or it will expand automatically based on the delay and scroll settings below.', 'salyut-agents' ); ?></p>
    <label class="salyut-agents-toggle">
        <input type="checkbox"
               name="salyut_agents_start_minimized"
               value="1"
               class="salyut-agents-toggle__input"
               <?php checked( $enabled, true ); ?> />
        <span class="salyut-agents-toggle__switch"></span>
        <span class="salyut-agents-toggle__label">
            <?php echo $enabled ? esc_html__( 'Start minimised', 'salyut-agents' ) : esc_html__( 'Start open (default)', 'salyut-agents' ); ?>
        </span>
    </label>
    <p class="description" style="margin-top: 8px;">
        <?php esc_html_e( 'Note: once a visitor manually opens or closes the widget, their preference is remembered for the rest of their session and overrides these settings.', 'salyut-agents' ); ?>
    </p>
    <?php
}

function salyut_agents_open_delay_render() {
    $value = (int) get_option( 'salyut_agents_open_delay', 0 );
    ?>
    <p class="description"><?php echo wp_kses( __( 'Automatically expand the widget after this many seconds if the visitor has not already interacted with it. Only applies when <strong>Start Minimised</strong> is on. Set to <strong>0</strong> to disable.', 'salyut-agents' ), [ 'strong' => [] ] ); ?></p>
    <input type="number"
           name="salyut_agents_open_delay"
           value="<?php echo esc_attr( $value ); ?>"
           min="0"
           max="120"
           class="small-text" /> seconds
    <?php if ( $value > 0 ) : ?>
        <p class="description">Widget will expand <?php echo esc_html( $value ); ?> second<?php echo $value === 1 ? '' : 's'; ?> after page load.</p>
    <?php endif; ?>
    <?php
}

function salyut_agents_scroll_threshold_render() {
    $value = (int) get_option( 'salyut_agents_scroll_threshold', 0 );
    ?>
    <p class="description"><?php echo wp_kses( __( 'Automatically expand the widget once the visitor has scrolled this many pixels down the page. Only applies when <strong>Start Minimised</strong> is on. Set to <strong>0</strong> to disable.', 'salyut-agents' ), [ 'strong' => [] ] ); ?></p>
    <input type="number"
           name="salyut_agents_scroll_threshold"
           value="<?php echo esc_attr( $value ); ?>"
           min="0"
           max="5000"
           step="50"
           class="small-text" /> px
    <?php if ( $value > 0 ) : ?>
        <p class="description">Widget will expand after <?php echo esc_html( $value ); ?>px of scroll.</p>
    <?php endif; ?>
    <?php
}

// ---------------------------------------------------------------------------
// Reusable security notice
// ---------------------------------------------------------------------------

/**
 * Echo a low-key notice linking to the security best-practices documentation.
 * Reusable across settings sections that touch bot/abuse protection.
 */
function salyut_agents_render_security_notice() {
    $doc_url = 'https://salyutplugins.com/salyut-agents/documentation/security';
    ?>
    <p class="description" style="color:#C0250C;font-weight:bold;">
        <?php esc_html_e( 'Proper security configuration reduces the risk of bot abuse and unexpectedly high API bills.', 'salyut-agents' ); ?>
        <a href="<?php echo esc_url( $doc_url ); ?>" target="_blank" rel="noopener noreferrer">
            <?php esc_html_e( 'Read our security best practices', 'salyut-agents' ); ?> ↗
        </a>
    </p>
    <?php
}

// ---------------------------------------------------------------------------
// Security tab — read-only overview of the always-on protections + spend cap
// reminder. Informational only: no settings fields, nothing to save here.
// ---------------------------------------------------------------------------

function salyut_agents_security_overview_render() {
    ?>
    <p class="description">
        <?php esc_html_e( 'These protections are always on — they run automatically on every chat and cannot be turned off. The settings below add further, optional layers on top.', 'salyut-agents' ); ?>
    </p>
    <ul style="list-style:disc;margin:0 0 1em 1.4em;max-width:46em;">
        <li>
            <strong><?php esc_html_e( 'Honeypot', 'salyut-agents' ); ?></strong> —
            <?php esc_html_e( 'a hidden field that silently blocks bots that autofill it. Always on.', 'salyut-agents' ); ?>
        </li>
        <li>
            <strong><?php esc_html_e( 'Timing check', 'salyut-agents' ); ?></strong> —
            <?php esc_html_e( 'rejects submissions completed impossibly fast for a human. Always on.', 'salyut-agents' ); ?>
        </li>
        <li>
            <strong><?php esc_html_e( 'Rate limiting', 'salyut-agents' ); ?></strong> —
            <?php esc_html_e( 'per-session, per-minute, and per-IP limits on chat activity. Always on.', 'salyut-agents' ); ?>
        </li>
    </ul>

    <div class="notice notice-error inline" style="max-width:46em;margin:1em 0;padding:8px 12px;">
        <p style="margin:0.4em 0;">
            <strong><?php esc_html_e( 'Set a spend cap in your AI provider\'s dashboard.', 'salyut-agents' ); ?></strong>
            <?php esc_html_e( 'The single strongest protection against unexpected API costs is a hard spending limit set with your provider — OpenAI, Anthropic, or Google. The protections on this page are layers on top of that ceiling; they reduce abuse but do not replace a provider-side spend cap.', 'salyut-agents' ); ?>
        </p>
    </div>

    <?php salyut_agents_render_security_notice(); ?>
    <?php
}

// ---------------------------------------------------------------------------
// Visitor IP detection field render callback
// ---------------------------------------------------------------------------

function salyut_agents_ip_source_render() {
    $source        = get_option( 'salyut_agents_ip_source', 'direct' );
    $custom_header = get_option( 'salyut_agents_ip_custom_header', '' );

    $options = [
        'direct'     => __( 'Direct connection (no CDN/proxy)', 'salyut-agents' ),
        'cloudflare' => __( 'Cloudflare', 'salyut-agents' ),
        'akamai'     => __( 'Akamai', 'salyut-agents' ),
        'sucuri'     => __( 'Sucuri', 'salyut-agents' ),
        'custom'     => __( 'Custom header', 'salyut-agents' ),
    ];
    ?>
    <p class="description"><?php echo esc_html__( 'Tell the plugin how your site is fronted so it can read each visitor\'s real IP address. This IP is what the per-IP rate limits are counted against.', 'salyut-agents' ); ?></p>
    <select name="salyut_agents_ip_source" id="salyut_agents_ip_source">
        <?php foreach ( $options as $val => $label ) : ?>
            <option value="<?php echo esc_attr( $val ); ?>" <?php selected( $source, $val ); ?>><?php echo esc_html( $label ); ?></option>
        <?php endforeach; ?>
    </select>

    <p id="salyut_agents_ip_custom_header_row" style="margin-top:10px;<?php echo $source === 'custom' ? '' : 'display:none;'; ?>">
        <label for="salyut_agents_ip_custom_header"><strong><?php esc_html_e( 'Custom header name', 'salyut-agents' ); ?></strong></label><br/>
        <input type="text"
               name="salyut_agents_ip_custom_header"
               id="salyut_agents_ip_custom_header"
               value="<?php echo esc_attr( $custom_header ); ?>"
               class="regular-text"
               placeholder="CF-Connecting-IP" />
        <br/>
        <span class="description"><?php esc_html_e( 'The exact single-value header your CDN sets. Multi-value/spoofable headers (X-Forwarded-For, X-Real-IP, Client-IP) are not allowed.', 'salyut-agents' ); ?></span>
    </p>

    <p class="description" style="margin-top:10px;">
        <?php esc_html_e( 'Direct connection is the safe choice for sites with no CDN or reverse proxy — the visitor IP is taken from REMOTE_ADDR. If your site sits behind a CDN, selecting it lets the plugin read the real visitor IP from that CDN\'s edge header, so rate limits apply per-visitor instead of collapsing everyone behind the CDN into a single bucket.', 'salyut-agents' ); ?>
    </p>
    <p class="description" style="color:#996800;">
        <?php echo wp_kses( __( '<strong>Security warning:</strong> a chosen header is only trustworthy if your origin server is locked down to accept traffic <em>only</em> from your CDN. Otherwise an attacker can bypass the CDN, connect to your origin directly, and forge that header to spoof any IP they like.', 'salyut-agents' ), [ 'strong' => [], 'em' => [] ] ); ?>
    </p>
    <?php
    // The change-listener that toggles the custom-header row lives in
    // admin/js/salyut-agents-admin.js (already enqueued on this screen).
}

// ---------------------------------------------------------------------------
// Bot protection (Turnstile) field render callbacks
// ---------------------------------------------------------------------------

function salyut_agents_turnstile_enabled_render() {
    $enabled = (bool) get_option( 'salyut_agents_turnstile_enabled', false );
    ?>
    <p class="description">
        <?php esc_html_e( 'Cloudflare Turnstile is a free, privacy-friendly CAPTCHA alternative. When enabled, every new chat session must pass a mostly-invisible challenge before it starts — the strongest of the bot protections. Recommended for public-facing sites; leave off for internal sites.', 'salyut-agents' ); ?>
    </p>
    <label class="salyut-agents-toggle">
        <input type="checkbox"
               name="salyut_agents_turnstile_enabled"
               value="1"
               class="salyut-agents-toggle__input"
               <?php checked( $enabled, true ); ?> />
        <span class="salyut-agents-toggle__switch"></span>
        <span class="salyut-agents-toggle__label">
            <?php echo $enabled ? esc_html__( 'Enabled', 'salyut-agents' ) : esc_html__( 'Disabled', 'salyut-agents' ); ?>
        </span>
    </label>
    <p class="description" style="margin-top:8px;">
        <?php echo wp_kses( __( 'Get your Site Key and Secret Key by creating a widget in the <strong>Cloudflare Turnstile dashboard</strong>.', 'salyut-agents' ), [ 'strong' => [] ] ); ?>
    </p>
    <p class="description">
        <?php
        $doc_url = 'https://salyutplugins.com/salyut-agents/documentation/security';
        echo wp_kses(
            sprintf(
                /* translators: %s: URL of the security documentation page. */
                __( 'When creating your Turnstile widget in the Cloudflare dashboard, choose widget type <strong>Managed</strong> (recommended) or <strong>Invisible</strong> — not Non-Interactive, which clutters the chat. Add your site\'s domain to the widget\'s allowed hostnames, then copy the Site Key and Secret Key below. See the <a href="%s" target="_blank" rel="noopener noreferrer">security documentation</a> for full setup steps.', 'salyut-agents' ),
                esc_url( $doc_url )
            ),
            [
                'strong' => [],
                'a'      => [ 'href' => [], 'target' => [], 'rel' => [] ],
            ]
        );
        ?>
    </p>
    <?php
    // The docs-link security notice now renders once at the top of the Security tab
    // (salyut_agents_security_overview_render), so it is intentionally not repeated here.
}

function salyut_agents_turnstile_site_key_render() {
    $value = get_option( 'salyut_agents_turnstile_site_key', '' );
    ?>
    <p class="description"><?php esc_html_e( 'Your Turnstile Site Key (public). Sent to the browser to render the challenge. Only used when Turnstile is enabled.', 'salyut-agents' ); ?></p>
    <input type="text"
           name="salyut_agents_turnstile_site_key"
           value="<?php echo esc_attr( $value ); ?>"
           class="regular-text"
           placeholder="0x4AAAAAAA..." />
    <?php
}

function salyut_agents_turnstile_secret_key_render() {
    $value = get_option( 'salyut_agents_turnstile_secret_key', '' );
    ?>
    <p class="description"><?php esc_html_e( 'Your Turnstile Secret Key (private). Used only server-side to verify tokens — it is never sent to the browser or exposed in any response.', 'salyut-agents' ); ?></p>
    <input type="password"
           name="salyut_agents_turnstile_secret_key"
           value="<?php echo esc_attr( $value ); ?>"
           class="regular-text"
           autocomplete="off"
           placeholder="0x4AAAAAAA..." />
    <?php
}

function salyut_agents_header_text_color_render() {
    $color = get_option( 'salyut_agents_header_text_color', '' );
    echo '<p class="description">' . esc_html__( 'Text colour in the chat header.', 'salyut-agents' ) . '</p>';
    echo '<input type="text" name="salyut_agents_header_text_color" id="salyut_agents_header_text_color" value="' . esc_attr( $color ) . '" class="salyut-agents-color-picker" data-default-color="" />';
}

function salyut_agents_dept_color_render() {
    $color = get_option( 'salyut_agents_dept_color', '#888888' );
    echo '<p class="description">' . esc_html__( 'Colour of the agent department label shown in the chat header.', 'salyut-agents' ) . '</p>';
    echo '<input type="text" name="salyut_agents_dept_color" id="salyut_agents_dept_color" value="' . esc_attr( $color ) . '" class="salyut-agents-color-picker" data-default-color="#888888" />';
}

function salyut_agents_bot_bubble_bg_render() {
    $color = get_option( 'salyut_agents_bot_bubble_bg', '' );
    echo '<p class="description">' . esc_html__( 'Background colour of bot chat bubbles.', 'salyut-agents' ) . '</p>';
    echo '<input type="text" name="salyut_agents_bot_bubble_bg" id="salyut_agents_bot_bubble_bg" value="' . esc_attr( $color ) . '" class="salyut-agents-color-picker" data-default-color="" />';
}

function salyut_agents_bot_bubble_text_render() {
    $color = get_option( 'salyut_agents_bot_bubble_text', '' );
    echo '<p class="description">' . esc_html__( 'Text colour of bot chat bubbles.', 'salyut-agents' ) . '</p>';
    echo '<input type="text" name="salyut_agents_bot_bubble_text" id="salyut_agents_bot_bubble_text" value="' . esc_attr( $color ) . '" class="salyut-agents-color-picker" data-default-color="" />';
}

function salyut_agents_user_bubble_bg_render() {
    $color = get_option( 'salyut_agents_user_bubble_bg', '' );
    echo '<p class="description">' . esc_html__( 'Background colour of user chat bubbles.', 'salyut-agents' ) . '</p>';
    echo '<input type="text" name="salyut_agents_user_bubble_bg" id="salyut_agents_user_bubble_bg" value="' . esc_attr( $color ) . '" class="salyut-agents-color-picker" data-default-color="" />';
}

function salyut_agents_user_bubble_text_render() {
    $color = get_option( 'salyut_agents_user_bubble_text', '' );
    echo '<p class="description">' . esc_html__( 'Text colour of user chat bubbles.', 'salyut-agents' ) . '</p>';
    echo '<input type="text" name="salyut_agents_user_bubble_text" id="salyut_agents_user_bubble_text" value="' . esc_attr( $color ) . '" class="salyut-agents-color-picker" data-default-color="" />';
}

function salyut_agents_minimize_btn_color_render() {
    $color = get_option( 'salyut_agents_minimize_btn_color', '' );
    echo '<p class="description">' . esc_html__( 'Colour of the − (minus) icon in the chat header that minimises the widget.', 'salyut-agents' ) . '</p>';
    echo '<input type="text" name="salyut_agents_minimize_btn_color" id="salyut_agents_minimize_btn_color" value="' . esc_attr( $color ) . '" class="salyut-agents-color-picker" data-default-color="" />';
}

function salyut_agents_switch_btn_color_render() {
    $color = get_option( 'salyut_agents_switch_btn_color', '' );
    echo '<p class="description">' . esc_html__( 'Background colour of the floating button that reopens the chat widget when it is minimised.', 'salyut-agents' ) . '</p>';
    echo '<input type="text" name="salyut_agents_switch_btn_color" id="salyut_agents_switch_btn_color" value="' . esc_attr( $color ) . '" class="salyut-agents-color-picker" data-default-color="" />';
}

function salyut_agents_switch_agent_btn_bg_render() {
    $color = get_option( 'salyut_agents_switch_agent_btn_bg', '' );
    echo '<p class="description">' . esc_html__( 'Background colour of the "Yes, switch agents" button in the agent handoff prompt.', 'salyut-agents' ) . '</p>';
    echo '<input type="text" name="salyut_agents_switch_agent_btn_bg" id="salyut_agents_switch_agent_btn_bg" value="' . esc_attr( $color ) . '" class="salyut-agents-color-picker" data-default-color="" />';
}

function salyut_agents_switch_agent_btn_text_render() {
    $color = get_option( 'salyut_agents_switch_agent_btn_text', '' );
    echo '<p class="description">' . esc_html__( 'Text colour of the "Yes, switch agents" button in the agent handoff prompt.', 'salyut-agents' ) . '</p>';
    echo '<input type="text" name="salyut_agents_switch_agent_btn_text" id="salyut_agents_switch_agent_btn_text" value="' . esc_attr( $color ) . '" class="salyut-agents-color-picker" data-default-color="" />';
}

function salyut_agents_border_radius_render() {
    $value = get_option( 'salyut_agents_border_radius', 16 );
    ?>
    <input type="number"
        name="salyut_agents_border_radius"
        value="<?php echo esc_attr( $value ); ?>"
        min="0"
        max="32"
        class="small-text" /> px
    <p class="description">
        <?php esc_html_e( 'Controls the rounding of the top corners of the chat widget. Default is 16px.', 'salyut-agents' ); ?>
    </p>
    <?php
}

function salyut_agents_widget_height_render() {
    $mode = get_option( 'salyut_agents_widget_height_mode', 'default' );
    $px   = salyut_agents_sanitize_widget_height_px( get_option( 'salyut_agents_widget_height_px', SALYUT_AGENTS_WIDGET_HEIGHT_DEFAULT_PX ) );
    ?>
    <select name="salyut_agents_widget_height_mode" id="salyut_agents_widget_height_mode">
        <option value="default" <?php selected( $mode, 'default' ); ?>><?php esc_html_e( 'Default', 'salyut-agents' ); ?></option>
        <option value="custom" <?php selected( $mode, 'custom' ); ?>><?php esc_html_e( 'Custom', 'salyut-agents' ); ?></option>
    </select>

    <p id="salyut_agents_widget_height_px_row" style="margin-top:10px;<?php echo 'custom' === $mode ? '' : 'display:none;'; ?>">
        <label for="salyut_agents_widget_height_px"><strong><?php esc_html_e( 'Height', 'salyut-agents' ); ?></strong></label><br/>
        <input type="number"
               name="salyut_agents_widget_height_px"
               id="salyut_agents_widget_height_px"
               value="<?php echo esc_attr( $px ); ?>"
               min="<?php echo esc_attr( SALYUT_AGENTS_WIDGET_HEIGHT_MIN_PX ); ?>"
               max="<?php echo esc_attr( SALYUT_AGENTS_WIDGET_HEIGHT_MAX_PX ); ?>"
               class="small-text" /> px
        <p class="description">
            <?php
            echo esc_html(
                sprintf(
                    /* translators: 1: minimum height in pixels, 2: maximum height in pixels */
                    __( 'Between %1$dpx and %2$dpx.', 'salyut-agents' ),
                    absint( SALYUT_AGENTS_WIDGET_HEIGHT_MIN_PX ),
                    absint( SALYUT_AGENTS_WIDGET_HEIGHT_MAX_PX )
                )
            );
            ?>
        </p>
    </p>

    <p class="description" style="margin-top:10px;">
        <?php esc_html_e( 'Default matches the widget\'s original height exactly. On a short screen (a phone in landscape, or a small embedded window), the widget automatically shrinks to fit — whatever height is set here, it never grows taller than the visitor\'s own visible screen.', 'salyut-agents' ); ?>
    </p>
    <?php
    // The change-listener that toggles the pixel-value row lives in
    // admin/js/salyut-agents-admin.js (already enqueued on this screen) —
    // same pattern as salyut_agents_ip_source_render()'s own custom-header row.
}

// ---------------------------------------------------------------------------
// Sanitization callbacks
// ---------------------------------------------------------------------------

function salyut_agents_sanitize_field_state( $input ) {
    $valid = [ 'off', 'optional', 'required' ];
    return in_array( $input, $valid, true ) ? $input : 'optional';
}

/**
 * Validates an owner-submitted override of the default model against every
 * currently-known model id (including deprecated ones, same as the agent
 * editor's own save handler — a model already saved somewhere should not
 * become impossible to re-select for this purpose either). An invalid
 * submission keeps whatever was already stored, rather than falling back to
 * empty — this is a deliberate write to a setting the owner can see, so a
 * bad value here is not the "could not determine" case that
 * salyut_agents_resolve_default_model_once() also has to handle.
 *
 * @param string $input
 * @return string
 */
function salyut_agents_sanitize_default_model_override( $input ) {
    $valid = array_keys( salyut_agents_get_available_models() );
    return in_array( $input, $valid, true ) ? $input : get_option( 'salyut_agents_default_model_resolved', '' );
}

function salyut_agents_sanitize_ip_source( $input ) {
    $valid = [ 'direct', 'cloudflare', 'akamai', 'sucuri', 'custom' ];
    return in_array( $input, $valid, true ) ? $input : 'direct';
}

function salyut_agents_sanitize_ip_custom_header( $input ) {
    // Strip to a valid HTTP header name: letters, digits and hyphens only.
    $header = preg_replace( '/[^A-Za-z0-9-]/', '', (string) $input );

    // Reject the multi-value / spoofable headers outright. These must never be
    // trusted as a single-value client IP source; the owner needs a dedicated
    // header their CDN sets at its edge instead.
    $banned = [ 'x-forwarded-for', 'x-real-ip', 'client-ip' ];
    if ( in_array( strtolower( $header ), $banned, true ) ) {
        add_settings_error(
            'salyut_agents_ip_custom_header',
            'salyut_agents_ip_custom_header_banned',
            __( 'X-Forwarded-For, X-Real-IP and Client-IP are multi-value and client-spoofable, so they are not allowed as a visitor IP source. Enter a dedicated single-value header that your CDN sets at its edge (for example CF-Connecting-IP or True-Client-IP).', 'salyut-agents' ),
            'error'
        );
        return '';
    }

    return $header;
}

function salyut_agents_sanitize_widget_height_mode( $input ) {
    return ( 'custom' === $input ) ? 'custom' : 'default';
}

/**
 * Clamps to [SALYUT_AGENTS_WIDGET_HEIGHT_MIN_PX, _MAX_PX], defaulting to
 * SALYUT_AGENTS_WIDGET_HEIGHT_DEFAULT_PX for anything non-numeric (an
 * empty field, a pasted word, etc.) rather than clamping a meaningless 0
 * up to the floor — a blank/garbage input becomes a sane starting value,
 * not silently the minimum. Used both here (on save) and again in
 * includes/widget.php (on render), per the task's own requirement that
 * this bound can never be bypassed by a value written any other way.
 */
function salyut_agents_sanitize_widget_height_px( $input ) {
    if ( ! is_numeric( $input ) ) {
        return SALYUT_AGENTS_WIDGET_HEIGHT_DEFAULT_PX;
    }
    return max( SALYUT_AGENTS_WIDGET_HEIGHT_MIN_PX, min( SALYUT_AGENTS_WIDGET_HEIGHT_MAX_PX, absint( $input ) ) );
}

/**
 * WAF-safe sanitizers for the long free-text agent fields (prompts, welcome
 * message, handoff line).
 *
 * Why base64: agent instructions routinely contain fragments that shared-host
 * WAFs / mod_security rule sets treat as attacks — SQL-ish phrases ("drop the
 * formalities"), angle brackets, "SELECT the option that…", code snippets — and
 * silently 403 the POST, losing the admin's work. The editor JS base64-encodes
 * these fields on submit so the request body is opaque to those rules; this
 * decodes them here.
 *
 * Safety: base64_decode() is used in strict mode and the result is trusted ONLY
 * when it round-trips (base64_encode(decode) === input). Anything else — a
 * genuine plain-text value from a browser with JS disabled, or a malformed
 * payload — falls through to being treated as raw input. Either way the value
 * is then run through wp_kses_post() / sanitize_textarea_field() before use, so
 * the decode step never widens what is accepted.
 */
function salyut_agents_sanitize_html_field( $input ) {
    $decoded = base64_decode( $input, true );
    $value   = ( $decoded !== false && base64_encode( $decoded ) === $input ) ? $decoded : $input;
    return wp_kses_post( $value );
}

function salyut_agents_sanitize_text_field_b64( $input ) {
    $decoded = base64_decode( $input, true );
    $value   = ( $decoded !== false && base64_encode( $decoded ) === $input ) ? $decoded : $input;
    return sanitize_textarea_field( $value );
}

// ---------------------------------------------------------------------------
// Admin menu
// ---------------------------------------------------------------------------

function salyut_agents_add_admin_menu() {
    remove_submenu_page( 'edit.php?post_type=salyut_lead', 'edit.php?post_type=salyut_lead' );

    $display_name = salyut_agents_display_name();

    add_submenu_page(
        'edit.php?post_type=salyut_lead',
        __( 'Get Started', 'salyut-agents' ),
        __( 'Get Started', 'salyut-agents' ),
        'manage_options',
        'salyut-agents-get-started',
        'salyut_agents_render_get_started_page'
    );

    add_submenu_page(
        'edit.php?post_type=salyut_lead',
        __( 'Leads', 'salyut-agents' ),
        __( 'Leads', 'salyut-agents' ),
        'manage_options',
        'edit.php?post_type=salyut_lead&view=list'
    );

    add_submenu_page(
        'edit.php?post_type=salyut_lead',
        /* translators: %s: product display name */
        sprintf( __( '%s Settings', 'salyut-agents' ), $display_name ),
        __( 'Settings', 'salyut-agents' ),
        'manage_options',
        'salyut-agents-settings',
        'salyut_agents_render_settings_page'
    );
}
add_action( 'admin_menu', 'salyut_agents_add_admin_menu', 9 );

add_action( 'load-edit.php', function() {
    // phpcs:disable WordPress.Security.NonceVerification.Recommended -- reading the request only to detect which core list screen is loading; no data is processed or written.
    $post_type   = sanitize_text_field( wp_unslash( $_GET['post_type']   ?? '' ) );
    $page        = sanitize_text_field( wp_unslash( $_GET['page']        ?? '' ) );
    $view        = sanitize_text_field( wp_unslash( $_GET['view']        ?? '' ) );
    $post_status = sanitize_text_field( wp_unslash( $_GET['post_status'] ?? '' ) );
    $action      = sanitize_text_field( wp_unslash( $_REQUEST['action']  ?? '' ) );
    $action2     = sanitize_text_field( wp_unslash( $_REQUEST['action2'] ?? '' ) );
    // phpcs:enable WordPress.Security.NonceVerification.Recommended

    $is_bulk_action = ( ! empty( $action ) && $action !== '-1' ) || ( ! empty( $action2 ) && $action2 !== '-1' );

    if ( $post_type === 'salyut_lead' && empty( $page ) && empty( $view ) && empty( $post_status ) && ! $is_bulk_action ) {
        wp_safe_redirect( admin_url( 'edit.php?post_type=salyut_lead&page=salyut-agents-get-started' ) );
        exit;
    }
});

// ---------------------------------------------------------------------------
// Fix admin menu highlighting
// ---------------------------------------------------------------------------

add_filter( 'parent_file', 'salyut_agents_fix_menu_highlight' );
add_filter( 'submenu_file', 'salyut_agents_fix_submenu_highlight' );

function salyut_agents_fix_menu_highlight( $parent_file ) {
    $screen = get_current_screen();
    if ( ! $screen ) return $parent_file;

    if ( $screen->post_type === 'salyut_lead' && $screen->base === 'post' ) {
        return 'edit.php?post_type=salyut_lead';
    }

    return $parent_file;
}

function salyut_agents_fix_submenu_highlight( $submenu_file ) {
    $screen = get_current_screen();
    if ( ! $screen ) return $submenu_file;

    // phpcs:ignore WordPress.Security.NonceVerification.Recommended -- reading the request only to detect the current admin screen for menu highlighting; nothing is processed.
    $is_leads_list = $screen->base === 'edit' && $screen->post_type === 'salyut_lead' && empty( $_GET['page'] );
    $is_leads_post = $screen->base === 'post' && $screen->post_type === 'salyut_lead';

    if ( $is_leads_list || $is_leads_post ) {
        return 'edit.php?post_type=salyut_lead&view=list';
    }

    return $submenu_file;
}

// ---------------------------------------------------------------------------
// Settings page renderer
// ---------------------------------------------------------------------------

function salyut_agents_render_settings_page() {
    if ( ! current_user_can( 'manage_options' ) ) return;

    // phpcs:ignore WordPress.Security.NonceVerification.Recommended -- reading the request only to pick which settings tab to render; the form itself is protected by the Settings API nonce on save.
    $current_tab = sanitize_text_field( wp_unslash( $_GET['tab'] ?? 'general' ) );
    $base_url    = admin_url( 'edit.php?post_type=salyut_lead&page=salyut-agents-settings' );

    ?>
    <div class="wrap">
        <h1><?php echo esc_html( get_admin_page_title() ); ?></h1>
        <?php settings_errors(); ?>

        <nav class="nav-tab-wrapper">
            <a href="<?php echo esc_url( $base_url . '&tab=general' ); ?>"
               class="nav-tab <?php echo $current_tab === 'general' ? 'nav-tab-active' : ''; ?>">
                <?php esc_html_e( 'General', 'salyut-agents' ); ?>
            </a>
            <a href="<?php echo esc_url( $base_url . '&tab=design' ); ?>"
               class="nav-tab <?php echo $current_tab === 'design' ? 'nav-tab-active' : ''; ?>">
                <?php esc_html_e( 'Design', 'salyut-agents' ); ?>
            </a>
            <a href="<?php echo esc_url( $base_url . '&tab=security' ); ?>"
               class="nav-tab <?php echo $current_tab === 'security' ? 'nav-tab-active' : ''; ?>">
                <?php esc_html_e( 'Security', 'salyut-agents' ); ?>
            </a>
        </nav>

        <form action="options.php" method="post">
            <?php
            if ( $current_tab === 'design' ) {
                settings_fields( 'salyut_agents_design_group' );
                do_settings_sections( 'salyut-agents-chatbot-design' );
            } elseif ( $current_tab === 'security' ) {
                settings_fields( 'salyut_agents_security_group' );
                do_settings_sections( 'salyut-agents-chatbot-security' );
            } else {
                settings_fields( 'salyut_agents_general_group' );
                do_settings_sections( 'salyut-agents-chatbot-general' );
            }

            submit_button( __( 'Save Settings', 'salyut-agents' ), 'primary', 'save_settings' );
            ?>
        </form>
    </div>
    <?php
}