<?php
// Citami Connector — module. Loaded by citami-connector.php in a fixed
// order; never load this file on its own.
if (!defined('ABSPATH')) {
    exit;
}

/* ────────────────────────────────────────────────────────────────── */
/*  Helpers                                                            */
/* ────────────────────────────────────────────────────────────────── */

/**
 * Returns the API key stored in the plugin settings, falling back to
 * the build-time preload constant injected by the dashboard packager
 * (Round 10D). The wp_options value always wins when present, so a
 * user can rotate their key from /dashboard without having to download
 * a fresh ZIP.
 */
/**
 * The API key the plugin may use to talk to the platform: the one the site
 * owner saved (settings or guided first run). A key preloaded in a package
 * downloaded from the dashboard is only a proposal: it is shown in the first
 * run and becomes the saved key when the owner presses "Connect" (2.70.2,
 * WordPress.org guideline 7: no contact with external servers before an
 * explicit consent). Pass $include_preload = true only to display it.
 */
function citami_get_api_key($include_preload = false) {
    $opt = get_option('citami_api_key', '');
    if (is_string($opt) && trim($opt) !== '') {
        return trim($opt);
    }
    if ($include_preload) {
        return citami_preloaded_api_key();
    }
    return '';
}

/** The key preloaded in the package, or '' (the placeholder of the plain template counts as none). */
function citami_preloaded_api_key() {
    if (defined('CITAMI_PRELOADED_API_KEY')) {
        $preload = CITAMI_PRELOADED_API_KEY;
        if (is_string($preload) && $preload !== '' && $preload !== '') {
            return trim($preload);
        }
    }
    return '';
}

/**
 * 2.70.2 — a site that was already connected through a preloaded key
 * (a successful handshake is on record) keeps working after the update:
 * the key the owner had accepted by downloading the package becomes the
 * saved key once. A site that never connected waits for "Connect".
 */
function citami_adopt_preloaded_key_once() {
    if (citami_get_api_key() !== '' || citami_preloaded_api_key() === '') return;
    $health = get_option(CITAMI_HEALTH_OPT, array());
    if (is_array($health) && !empty($health['ok'])) {
        update_option('citami_api_key', citami_preloaded_api_key());
    }
}
add_action('init', 'citami_adopt_preloaded_key_once', 1);

/**
 * v2.7.1 — HEALTH-HANDSHAKE. Ping leggero a GET /api/plugin/health:
 * conferma che key + endpoint funzionano e fa aggiornare al server
 * sites.wp_api_key_last_ping (→ la dashboard passa a "Connesso").
 * L'endpoint server esisteva da tempo, progettato proprio per questo
 * ("plugin pings this on activation + periodically"), ma il plugin
 * non l'ha mai chiamato. Esito persistito in CITAMI_HEALTH_OPT per
 * il pannello Stato. Rate limit server: 60/min per key — i nostri
 * trigger (attivazione, salvataggio opzioni, cron throttled 6h,
 * render pagina admin throttled 60s) restano lontanissimi dal cap.
 */
function citami_health_ping() {
    $key = citami_get_api_key();
    if (empty($key)) {
        $result = array('ts' => time(), 'ok' => false, 'message' => citami_t('API key mancante', 'API key missing'));
        update_option(CITAMI_HEALTH_OPT, $result, false);
        return $result;
    }
    // 2.75.0 — ?lang= so the plan's list comes back in the WordPress language.
    $response = wp_remote_get(citami_get_endpoint() . '/api/plugin/health?lang=' . (function_exists('citami_lang') ? citami_lang() : 'en'), array(
        'timeout' => 10,
        'headers' => array(
            'Authorization' => 'Bearer ' . $key,
            'User-Agent'    => 'CitamiConnector/' . CITAMI_PLUGIN_VERSION . '; ' . home_url('/'),
        ),
    ));
    if (is_wp_error($response)) {
        $result = array('ts' => time(), 'ok' => false, 'message' => $response->get_error_message());
    } else {
        $code = (int) wp_remote_retrieve_response_code($response);
        if ($code >= 200 && $code < 300) {
            $body = json_decode(wp_remote_retrieve_body($response), true);
            $plan = (is_array($body) && !empty($body['plan'])) ? (string) $body['plan'] : '';
            $message = $plan === 'free'
                ? citami_t('OK — account gratuito', 'OK — free account')
                : ($plan !== '' ? sprintf(citami_t('OK — piano %s', 'OK — %s plan'), ucfirst($plan)) : 'OK');
            $result = array('ts' => time(), 'ok' => true, 'message' => $message, 'usage' => citami_usage_from_body($body), 'tier' => citami_tier_from_body($body), 'plan' => function_exists('citami_plan_from_body') ? citami_plan_from_body($body) : null, 'nudge' => function_exists('citami_nudge_from_body') ? citami_nudge_from_body($body) : null);
        } else {
            $message = 'HTTP ' . $code;
            if ($code === 401 || $code === 403) {
                $message .= ' — ' . citami_t('API key non valida o ruotata', 'API key invalid or rotated');
            } elseif ($code === 404) {
                $message .= ' — ' . citami_t('endpoint errato?', 'wrong endpoint?');
            }
            $result = array('ts' => time(), 'ok' => false, 'message' => $message);
        }
    }
    update_option(CITAMI_HEALTH_OPT, $result, false);
    return $result;
}

/* ---------------------------------------------------------------- */
/*  2.47 — monthly quotas (alt text, AEO drafts) from the health ping  */
/* ---------------------------------------------------------------- */

define('CITAMI_USAGE_NEAR_SHARE', 0.8);

/** Sanitises the `usage` block of /api/plugin/health; null when absent. */
function citami_usage_from_body($body) {
    if (!is_array($body) || !isset($body['usage']) || !is_array($body['usage'])) {
        return null;
    }
    $out = array();
    foreach (array('alt_text', 'aeo_draft') as $k) {
        $c = isset($body['usage'][$k]) && is_array($body['usage'][$k]) ? $body['usage'][$k] : null;
        if ($c === null || !isset($c['used'], $c['quota'])) {
            return null;
        }
        $out[$k] = array('used' => max(0, (int) $c['used']), 'quota' => max(0, (int) $c['quota']));
    }
    $resets = isset($body['usage']['resets_at']) ? strtotime((string) $body['usage']['resets_at']) : false;
    $out['resets_at'] = $resets ? (int) $resets : (int) strtotime('first day of next month midnight');
    return $out;
}

/** ok | near (80 %+) | exhausted. */
function citami_usage_level($used, $quota) {
    if ($quota <= 0 || $used >= $quota) return 'exhausted';
    if ($used >= $quota * CITAMI_USAGE_NEAR_SHARE) return 'near';
    return 'ok';
}

/** The last usage the platform told us, or null (older platform, never pinged). */
function citami_usage() {
    // 2.56.1 — no key, no quotas: a removed key used to keep showing the last plan's counters.
    if (citami_get_api_key() === '') {
        return null;
    }
    $health = get_option(CITAMI_HEALTH_OPT, array());
    if (!is_array($health) || empty($health['usage']) || !is_array($health['usage'])) {
        return null;
    }
    $u = $health['usage'];
    foreach (array('alt_text', 'aeo_draft') as $k) {
        if (!isset($u[$k]['used'], $u[$k]['quota'])) {
            return null;
        }
        $u[$k]['level'] = citami_usage_level((int) $u[$k]['used'], (int) $u[$k]['quota']);
    }
    return $u;
}

/** "12/300" for one counter, or '' when unknown. */
function citami_usage_fraction($kind) {
    $u = citami_usage();
    return $u && isset($u[$kind]) ? sprintf('%d/%d', (int) $u[$kind]['used'], (int) $u[$kind]['quota']) : '';
}

/** One line for Stato / Overview: "Alt text 12/300 · Bozze AI 4/150 · si azzerano il 1 ottobre". */
function citami_usage_summary() {
    $u = citami_usage();
    if ($u === null) {
        return '';
    }
    $labels = array('alt_text' => citami_t('Alt text', 'Alt texts'), 'aeo_draft' => citami_t('Bozze AI', 'AI drafts'));
    $parts = array();
    foreach ($labels as $k => $label) {
        $c = $u[$k];
        $suffix = $c['level'] === 'exhausted' ? ' (' . citami_t('finiti', 'used up') . ')' : ($c['level'] === 'near' ? ' (' . citami_t('quasi al limite', 'close to the limit') . ')' : '');
        $parts[] = sprintf('%s %d/%d%s', $label, (int) $c['used'], (int) $c['quota'], $suffix);
    }
    // 2.56.1 — the platform resets at 00:00 UTC on the 1st: shown in UTC
    // (a site behind UTC read "30 September"), and a reset already past
    // (data from before the month turned) rolls to the next one.
    $reset = (int) $u['resets_at'];
    if ($reset <= time()) $reset = (int) strtotime(gmdate('Y-m-01 00:00:00', strtotime('first day of next month', time())) . ' UTC');
    return implode(' · ', $parts) . ' · ' . sprintf(citami_t('si azzerano il %s', 'reset on %s'), wp_date('j F', $reset, new DateTimeZone('UTC')));
}

/** Worst level across the counters: drives the colour. */
function citami_usage_worst_level() {
    $u = citami_usage();
    if ($u === null) return 'ok';
    $rank = array('ok' => 0, 'near' => 1, 'exhausted' => 2);
    $worst = 'ok';
    foreach (array('alt_text', 'aeo_draft') as $k) {
        if ($rank[$u[$k]['level']] > $rank[$worst]) $worst = $u[$k]['level'];
    }
    return $worst;
}

/* ---------------------------------------------------------------- */
/*  2.46 — one connection state for the pill, the Overview and Stato   */
/* ---------------------------------------------------------------- */

define('CITAMI_CRON_LAST_RUN_OPT', 'citami_cron_last_run');
/** WP-Cron silent for longer than this = "the dashboard will stop hearing from us". */
define('CITAMI_CRON_STALL_SECONDS', 2 * HOUR_IN_SECONDS);

/** Called by every cron handler: proof that WP-Cron actually runs on this site. */
function citami_cron_heartbeat() {
    update_option(CITAMI_CRON_LAST_RUN_OPT, time(), false);
}

/** Seconds since WP-Cron last ran one of our jobs, or null when it never did. */
function citami_cron_silence() {
    $last = (int) get_option(CITAMI_CRON_LAST_RUN_OPT, 0);
    return $last > 0 ? max(0, time() - $last) : null;
}

/**
 * The one answer to "is this site connected?", with the reason and the
 * next step. The dashboard reads the health ping the cron sends every
 * 25 minutes; when WP-Cron does not run (no visits, DISABLE_WP_CRON
 * without a system cron) the plugin still says "connected" while the
 * dashboard stops hearing from it. That contradiction is a state here.
 *
 *   none     — no API key
 *   pending  — key set, first handshake not done yet (pinged now)
 *   failed   — last handshake failed (message says why)
 *   cron     — handshake fine, but WP-Cron silent for 2 h+
 *   ok       — connected and talking
 */
function citami_connection_state() {
    $key = citami_get_api_key();
    if ($key === '') {
        return array('state' => 'none', 'class' => 'warn',
            'label' => citami_t('Non collegato', 'Not connected'),
            'hint'  => citami_t('Collega il sito: crea un account gratuito e incolla la API key (dashboard → Impostazioni → Plugin).', 'Connect the site: create a free account and paste the API key (dashboard → Settings → Plugin).'),
            'href'  => function_exists('citami_setup_url') ? citami_setup_url(1) : admin_url('admin.php?page=citami-connector&tab=general'));
    }
    $health = get_option(CITAMI_HEALTH_OPT, array());
    if (!is_array($health) || empty($health['ts'])) {
        $health = citami_health_ping();
    }
    $ts = isset($health['ts']) ? (int) $health['ts'] : 0;
    $fmt = (string) get_option('time_format');
    $when = $ts > 0 ? wp_date($fmt !== '' ? $fmt : 'H:i', $ts) : '';
    $general = function_exists('citami_admin_url') ? citami_admin_url('general') : admin_url('admin.php?page=citami-connector&tab=general');
    if (empty($health['ok'])) {
        $msg = isset($health['message']) ? (string) $health['message'] : '';
        return array('state' => 'failed', 'class' => 'bad',
            'label' => citami_t('Collegamento non riuscito', 'Connection failed'),
            'hint'  => trim($msg . ' — ' . sprintf(citami_t('Controlla chiave ed endpoint in %s → Impostazioni, poi premi «Verifica connessione».', 'Check key and endpoint under %s → Settings, then press "Check connection".'), citami_brand_name()), ' —'),
            'href'  => $general);
    }
    $silence = citami_cron_silence();
    $cron_off = defined('DISABLE_WP_CRON') && DISABLE_WP_CRON;
    if ($silence !== null ? $silence > CITAMI_CRON_STALL_SECONDS : ($ts > 0 && time() - $ts > CITAMI_CRON_STALL_SECONDS)) {
        $hours = $silence !== null ? (int) floor($silence / HOUR_IN_SECONDS) : (int) floor((time() - $ts) / HOUR_IN_SECONDS);
        return array('state' => 'cron', 'class' => 'warn',
            'label' => citami_t('Collegato · cron fermo', 'Connected · cron stalled'),
            'hint'  => sprintf(
                $cron_off
                    ? citami_t('DISABLE_WP_CRON è attivo e nessun cron di sistema ha chiamato wp-cron.php da %d ore: la dashboard smette di ricevere il segnale e segna il sito come non connesso. Aggiungi un cron di sistema che chiami wp-cron.php ogni 5 minuti.', 'DISABLE_WP_CRON is on and no system cron has called wp-cron.php for %d hours: the dashboard stops receiving the signal and marks the site as not connected. Add a system cron calling wp-cron.php every 5 minutes.')
                    : citami_t('Il cron di WordPress non gira da %d ore (parte solo con le visite): la dashboard smette di ricevere il segnale e segna il sito come non connesso. Imposta un cron di sistema che chiami wp-cron.php ogni 5 minuti.', 'WordPress cron has not run for %d hours (it only fires on visits): the dashboard stops receiving the signal and marks the site as not connected. Set up a system cron calling wp-cron.php every 5 minutes.'),
                $hours),
            'href'  => $general);
    }
    return array('state' => 'ok', 'class' => 'ok',
        'label' => citami_t('Collegato a Citami', 'Connected to Citami'),
        'hint'  => $when !== '' ? sprintf(citami_t('Ultimo controllo alle %s.', 'Last check at %s.'), $when) : '',
        'href'  => $general);
}

/**
 * Re-handshake immediato quando key o endpoint cambiano dal form
 * impostazioni. updated_option scatta solo a valore cambiato;
 * added_option copre il primo salvataggio. Il ping stesso scrive
 * CITAMI_HEALTH_OPT, che non è tra le opzioni osservate → nessuna
 * ricorsione.
 */
function citami_health_on_option_change($option) {
    if ($option === 'citami_api_key' || $option === 'citami_endpoint') {
        citami_health_ping();
    }
}
add_action('updated_option', 'citami_health_on_option_change', 10, 1);
add_action('added_option', 'citami_health_on_option_change', 10, 1);

/**
 * Returns the Citami endpoint (default: https://citami.ai).
 */
/**
 * 2.56.1 — edit link that never comes back empty: get_edit_post_link()
 * returns null for a post the user cannot edit or that no longer exists,
 * which printed href="" (and a PHP 8.1 deprecation) in several lists.
 * Falls back to the public URL, then to ''.
 */
function citami_edit_link($post_id) {
    $post_id = is_object($post_id) && isset($post_id->ID) ? (int) $post_id->ID : (int) $post_id;
    $url = get_edit_post_link($post_id, 'raw');
    if (!$url) $url = get_permalink($post_id);
    return $url ? (string) $url : '';
}

/**
 * 2.56.1 — where a new user gets an account and the API key. The
 * register page sends them straight to Settings → Plugin afterwards.
 */
function citami_signup_url($campaign = 'setup') {
    $base = function_exists('citami_brand_site') ? citami_brand_site() : citami_default_endpoint();
    return citami_lang_url($base . '/register?redirect=' . rawurlencode('/dashboard/settings/plugin')
        . '&utm_source=wordpress&utm_medium=plugin&utm_campaign=' . rawurlencode(sanitize_key($campaign)));
}

/**
 * 2.73.3 — UI-LANG: a link to the CiteProof dashboard carries the language
 * of this WordPress (?lang=it / de / en), so the dashboard opens in it; the
 * platform stores the choice in a cookie. The Citami build points at the
 * Italian sites and needs nothing.
 */
function citami_lang_url($url) {
    $url = (string) $url;
    if (!function_exists('citami_brand') || citami_brand() !== 'citeproof' || !function_exists('citami_lang')) return $url;
    return $url . (strpos($url, '?') === false ? '?' : '&') . 'lang=' . citami_lang();
}

/** Key page in the dashboard, for users who already have an account. */
function citami_key_url() {
    $base = function_exists('citami_brand_site') ? citami_brand_site() : citami_default_endpoint();
    return citami_lang_url($base . '/dashboard/settings/plugin');
}

/** One line under every API key field: where to get one, with or without an account. */
function citami_get_key_html($campaign = 'setup') {
    // 2.74.0 — one click first (connect.php); the pasted key stays as the fallback.
    return (function_exists('citami_connect_button_html') ? citami_connect_button_html() : '')
        // 2.77.0 — QA: two purple buttons side by side ("Connect", "Create an account") read as two
        // different paths; the one-click button already creates the account. The key is the quiet fallback.
        . '<p class="citami-get-key description" data-citami="get-key">'
        . esc_html(citami_t('Hai già una chiave? La trovi in', 'Already have a key? It is in')) . ' '
        . '<a href="' . esc_url(citami_key_url()) . '" target="_blank" rel="noopener">' . esc_html(citami_t('Impostazioni → Plugin', 'Settings → Plugin')) . '</a>'
        . ' (' . esc_html(citami_t('account non ancora creato?', 'no account yet?')) . ' <a href="' . esc_url(citami_signup_url($campaign)) . '" target="_blank" rel="noopener">' . esc_html(citami_t('Crea un account gratuito', 'Create a free account')) . '</a>).</p>';
}

/**
 * 2.56.1 — country and phone prefix suggested in the forms, from the site
 * language (en_US → US / +1, de_DE → DE / +49). Placeholders only: nothing
 * is saved unless the user types it.
 */
function citami_locale_country() {
    $locale = function_exists('get_locale') ? (string) get_locale() : '';
    if (preg_match('/^[a-z]{2,3}_([A-Z]{2})/', $locale, $m)) return $m[1];
    $lang = strtolower(substr($locale, 0, 2));
    $by_lang = array('it' => 'IT', 'de' => 'DE', 'fr' => 'FR', 'es' => 'ES', 'nl' => 'NL', 'pt' => 'PT');
    return isset($by_lang[$lang]) ? $by_lang[$lang] : 'US';
}

function citami_locale_phone_hint() {
    $prefix = array('IT' => '+39', 'US' => '+1', 'CA' => '+1', 'GB' => '+44', 'IE' => '+353', 'AU' => '+61', 'NZ' => '+64', 'DE' => '+49', 'AT' => '+43', 'CH' => '+41', 'FR' => '+33', 'ES' => '+34', 'NL' => '+31', 'BE' => '+32', 'PT' => '+351');
    $c = citami_locale_country();
    return (isset($prefix[$c]) ? $prefix[$c] : '+') . ' …';
}

/** 2.56.1 — a post type as WordPress names it in the site language ("Pagine"), not its slug. */
function citami_post_type_label($type) {
    $obj = function_exists('get_post_type_object') ? get_post_type_object((string) $type) : null;
    if ($obj && isset($obj->labels->name) && $obj->labels->name !== '') return (string) $obj->labels->name;
    return ucfirst((string) $type);
}

/** Schema type choice as shown in a select: "None" reads as a word, the rest are schema.org names. */
function citami_schema_choice_label($c) {
    return $c === 'None' ? citami_t('Nessuno', 'None') : (string) $c;
}

/**
 * 2.57 — FREE-TIER: the account behind the key, as the platform says it
 * ("free" = signed up, nothing bought; "paid" = any plan, agent or trial).
 * '' when the platform is older and does not say: treated as paid, no
 * upgrade prompts.
 */
function citami_tier_from_body($body) {
    $t = is_array($body) && isset($body['tier']) ? (string) $body['tier'] : '';
    return in_array($t, array('free', 'paid'), true) ? $t : '';
}

/** none (no key) | free | paid. */
function citami_account_tier() {
    if (citami_get_api_key() === '') return 'none';
    $health = get_option(CITAMI_HEALTH_OPT, array());
    return is_array($health) && isset($health['tier']) && $health['tier'] === 'free' ? 'free' : 'paid';
}

function citami_is_free_account() {
    return citami_account_tier() === 'free';
}

/** Plans page in the dashboard (billing), tagged with where the click came from. */
function citami_upgrade_url($campaign = 'plugin') {
    $base = function_exists('citami_brand_site') ? citami_brand_site() : citami_default_endpoint();
    return citami_lang_url($base . '/dashboard/settings/billing?utm_source=wordpress&utm_medium=plugin&utm_campaign=' . rawurlencode(sanitize_key($campaign)));
}

/**
 * What a paid plan adds for one counter, in one line — shown next to a
 * free account's quota when it runs low or out. The paid numbers are the
 * platform's (lib/plugin/entitlements.ts PAID_PLUGIN_QUOTAS).
 */
function citami_upgrade_line($kind) {
    $paid = array('aeo_draft' => 150, 'alt_text' => 300, 'page_ai' => 200);
    $n = isset($paid[$kind]) ? $paid[$kind] : 0;
    $what = array(
        'aeo_draft' => citami_t('%d bozze AI al mese', '%d AI drafts a month'),
        'alt_text'  => citami_t('%d descrizioni di immagini al mese', '%d image descriptions a month'),
        'page_ai'   => citami_t('%d riscritture AI al mese', '%d AI rewrites a month'),
    );
    if ($kind === 'questions') {
        return citami_t('Con un piano: più domande tracciate, audit su 5 motori AI e correzioni automatiche.', 'With a plan: more tracked questions, audits on 5 AI engines and automatic fixes.');
    }
    if ($kind === 'fixes') {
        return citami_t('Con un piano la piattaforma prepara dopo ogni audit le correzioni per il sito (dati strutturati, meta tag, llms.txt, robots.txt): le approvi qui.', 'With a plan the platform prepares fixes for the site after every audit (structured data, meta tags, llms.txt, robots.txt): you approve them here.');
    }
    if (!$n || !isset($what[$kind])) return '';
    return sprintf(citami_t('Con un piano: %s, audit su 5 motori AI e correzioni automatiche.', 'With a plan: %s, audits on 5 AI engines and automatic fixes.'), sprintf($what[$kind], $n));
}

/** The upgrade link as HTML (a free account only; '' otherwise). */
function citami_upgrade_link_html($campaign, $label = '') {
    if (!citami_is_free_account()) return '';
    return '<a class="citami-upgrade-link" data-citami="upgrade" href="' . esc_url(citami_upgrade_url($campaign)) . '" target="_blank" rel="noopener">' . esc_html($label !== '' ? $label : citami_t('Passa a un piano', 'See the plans')) . '</a>';
}

/** A notice array as HTML: message, then the upgrade link when it carries one. */
function citami_notice_text_html(array $notice) {
    $html = esc_html(isset($notice['message']) ? (string) $notice['message'] : '');
    if (!empty($notice['upgrade']) && citami_is_free_account()) {
        $line = citami_upgrade_line((string) $notice['upgrade']);
        $html .= ($line !== '' ? ' ' . esc_html($line) : '') . ' ' . citami_upgrade_link_html('quota_' . sanitize_key((string) $notice['upgrade']));
    }
    return $html;
}

function citami_get_endpoint() {
    $endpoint = get_option('citami_endpoint', citami_default_endpoint());
    return rtrim(is_string($endpoint) && $endpoint ? $endpoint : citami_default_endpoint(), '/');
}

/**
 * Returns true when "review-only" mode is enabled (default: ON).
 *
 * In review-only mode, fixes are still queued in citami_fix_queue (so the
 * admin has a complete audit trail) but NOT auto-applied to wp_head /
 * llms.txt / robots.txt. This is the secure default — the admin opts
 * in to auto-application by toggling the setting off.
 */
function citami_is_review_only() {
    $val = get_option(CITAMI_REVIEW_ONLY_OPT, '1');
    return $val === '1' || $val === 1 || $val === true;
}

/**
 * Decides whether a single inbound apply-fix call should bypass
 * review-only mode. Two signals, header takes precedence:
 *
 *   X-Citami-Auto-Apply: 1   (per-call, server-controlled)
 *   CITAMI_PRELOADED_AUTO_APPLY_MODE === 'enabled'  (install-time)
 *
 * The header path is what makes auto-apply work on a v2.1.x install
 * that the customer hasn't re-downloaded yet — Citami's auto-push
 * cron stamps it on every queued push when the user has opted in.
 * The constant path is the belt-and-braces for cases where the
 * customer disables the WP-side review_only setting AND wants the
 * server to know about it.
 *
 * Both signals only OPT INTO auto-apply; nothing here can turn it
 * off if review_only is already false (the existing default-OFF
 * customers keep applying immediately as before).
 */
function citami_should_force_apply(WP_REST_Request $request) {
    $header = $request->get_header('x-citami-auto-apply');
    if ($header === '1') {
        return true;
    }
    if (defined('CITAMI_PRELOADED_AUTO_APPLY_MODE')) {
        $mode = CITAMI_PRELOADED_AUTO_APPLY_MODE;
        if (is_string($mode) && $mode === 'enabled') {
            return true;
        }
    }
    return false;
}

/**
 * 2.66 — "Pagine da escludere" (dashboard → applicazione automatica): on
 * these paths nothing from the platform's fixes is printed (schema and
 * meta blocks, the Yoast/Rank Math merge) and the FAQ page is not
 * created or rewritten. The list arrives with the sync pull. Same matcher
 * as lib/auto-apply/exclude-paths.ts:
 *   "/checkout"   → that page only;  "/checkout/*" → it and everything below.
 */
define('CITAMI_EXCLUDE_PATHS_OPT', 'citami_exclude_paths');

function citami_excluded_paths() {
    $list = get_option(CITAMI_EXCLUDE_PATHS_OPT, array());
    return is_array($list) ? array_values(array_filter($list, 'is_string')) : array();
}

function citami_path_is_excluded($path, $patterns = null) {
    $patterns = is_array($patterns) ? $patterns : citami_excluded_paths();
    if (empty($patterns)) return false;
    $p = (string) wp_parse_url((string) $path, PHP_URL_PATH);
    $p = rawurldecode($p === '' ? '/' : $p);
    foreach ($patterns as $pattern) {
        $pattern = trim((string) $pattern);
        if ($pattern === '') continue;
        $parts = explode('*', rtrim($pattern, '/'));
        $body = implode('.*', array_map(function ($x) { return preg_quote($x, '#'); }, $parts));
        $body = preg_replace('#/\.\*$#', '(?:/.*)?', $body);
        if (preg_match('#^' . $body . '/?$#i', $p)) return true;
    }
    return false;
}

/** The current front-end request is on an excluded page. */
function citami_fix_output_excluded() {
    if (is_admin() || !isset($_SERVER['REQUEST_URI'])) return false;
    return citami_path_is_excluded(sanitize_text_field(wp_unslash((string) $_SERVER['REQUEST_URI'])));
}

/**
 * 2.65 — mirror of lib/audit/schema-completeness.ts: what is missing for
 * this JSON-LD to go live (placeholders left by the generator, required
 * properties per @type). Empty array = complete. Takes the JSON string
 * returned by citami_validate_jsonld().
 */
function citami_schema_missing($safe_json) {
    $data = json_decode((string) $safe_json, true);
    if (!is_array($data)) return array('JSON-LD');
    $missing = array();
    citami_schema_scan_placeholders($data, '', $missing);
    if (isset($data['@graph']) && is_array($data['@graph'])) {
        $nodes = $data['@graph'];
    } elseif (isset($data[0])) {
        $nodes = $data;
    } else {
        $nodes = array($data);
    }
    foreach ($nodes as $node) {
        if (is_array($node)) citami_schema_check_node($node, $missing);
    }
    return array_values(array_unique($missing));
}

function citami_schema_placeholder_re() {
    $w = 'nome|telefono|indirizzo|prezzo|email|e-mail|cap|logo|url|sito|azienda|ragione sociale|partita iva|orari|via|numero|your|name|phone|address|price|city|zip|postal|company|website|insert|inserisci|inserire';
    return '/DA[_ ]?COMPILARE|DA[_ ]?INSERIRE|TO[_ ]?BE[_ ]?FILLED|\bTODO\b|\bTBD\b|\bXXX+\b|\blorem ipsum\b|\bplaceholder\b|\{\{[^}]*\}\}|\[[^\]]*\b(?:' . $w . ')\b[^\]]*\]|<[^<>]*\b(?:' . $w . ')\b[^<>]*>|^\[[^\]]+\]$|\bexample\.(?:com|org|net|it)\b|\b(?:your|tuo|tua|vostro|vostra) (?:company|phone|address|name|email|business|azienda|telefono|indirizzo|nome|logo|sito)\b|\b0{6,}\b|\b(?:123[- ]?456[- ]?789|555[- ]?0\d{3})\b/iu';
}

function citami_schema_scan_placeholders($v, $path, array &$out) {
    if (is_string($v)) {
        $t = trim($v);
        if ($t === '') {
            $out[] = 'empty: ' . ($path === '' ? 'value' : $path);
        } elseif (preg_match(citami_schema_placeholder_re(), $t, $m)) {
            $out[] = 'placeholder: ' . $m[0];
        }
        return;
    }
    if (is_array($v)) {
        foreach ($v as $k => $x) {
            if ($k === '@context') continue;
            citami_schema_scan_placeholders($x, $path === '' ? (string) $k : $path . '.' . $k, $out);
        }
    }
}

function citami_schema_filled($v) {
    if ($v === null) return false;
    if (is_string($v)) return trim($v) !== '';
    if (is_int($v) || is_float($v)) return true;
    if (is_array($v)) {
        foreach ($v as $k => $x) {
            if ($k === '@id' && is_string($x)) return true;
            if (is_string($k) && strpos($k, '@') === 0) continue;
            if (citami_schema_filled($x)) return true;
        }
        return false;
    }
    return (bool) $v;
}

function citami_schema_first($v) {
    return (is_array($v) && isset($v[0])) ? $v[0] : $v;
}

function citami_schema_is_local_business($type) {
    static $set = null;
    if ($set === null) {
        $set = array_flip(array_map('strtolower', array(
            'LocalBusiness', 'Store', 'OnlineStore', 'Restaurant', 'FoodEstablishment', 'Bakery', 'BarOrPub',
            'CafeOrCoffeeShop', 'IceCreamShop', 'Winery', 'Brewery', 'FastFoodRestaurant',
            'ProfessionalService', 'LegalService', 'Attorney', 'Notary', 'AccountingService', 'FinancialService',
            'InsuranceAgency', 'RealEstateAgent', 'TravelAgency', 'EmploymentAgency',
            'BeautySalon', 'HairSalon', 'NailSalon', 'DaySpa', 'HealthAndBeautyBusiness', 'TattooParlor',
            'Dentist', 'Physician', 'MedicalClinic', 'Hospital', 'Pharmacy', 'Optician', 'MedicalBusiness',
            'VeterinaryCare', 'Hotel', 'Motel', 'Resort', 'BedAndBreakfast', 'Hostel', 'LodgingBusiness',
            'Campground', 'AutoRepair', 'AutoDealer', 'AutomotiveBusiness', 'GasStation',
            'HomeAndConstructionBusiness', 'Electrician', 'Plumber', 'HVACBusiness', 'RoofingContractor',
            'GeneralContractor', 'HousePainter', 'Locksmith', 'MovingCompany',
            'SportsActivityLocation', 'ExerciseGym', 'HealthClub', 'SportsClub',
            'ChildCare', 'DryCleaningOrLaundry', 'EntertainmentBusiness', 'LibrarySystem',
            'ShoppingCenter', 'ClothingStore', 'ElectronicsStore', 'FurnitureStore', 'GroceryStore',
            'HardwareStore', 'JewelryStore', 'BookStore', 'Florist', 'PetStore', 'SportingGoodsStore',
            'ToyStore', 'TireShop', 'MobilePhoneStore', 'OfficeEquipmentStore', 'WholesaleStore',
            'SelfStorage', 'RecyclingCenter', 'RadioStation', 'TelevisionStation', 'TouristInformationCenter'
        )));
    }
    $t = strtolower(trim((string) $type));
    if ($t === '') return false;
    return strpos($t, 'business') !== false || isset($set[$t]);
}

function citami_schema_check_node(array $node, array &$out) {
    $types = array();
    if (isset($node['@type'])) {
        $types = is_array($node['@type']) ? array_values(array_filter($node['@type'], 'is_string')) : array((string) $node['@type']);
    }
    $label = isset($types[0]) ? $types[0] : 'Thing';
    $lower = array_map('strtolower', $types);
    $need = function ($prop) use ($node, $label, &$out) {
        if (!isset($node[$prop]) || !citami_schema_filled($node[$prop])) $out[] = $label . '.' . $prop;
    };
    $local = false;
    $identity = false;
    foreach ($types as $t) {
        if (citami_schema_is_local_business($t)) $local = true;
        if (stripos($t, 'organization') !== false || in_array(strtolower($t), array('corporation', 'ngo'), true)) $identity = true;
    }
    if ($local) {
        $need('name');
        $need('telephone');
        $addr = isset($node['address']) ? citami_schema_first($node['address']) : null;
        if (!is_array($addr)) {
            $out[] = $label . '.address';
        } else {
            foreach (array('streetAddress', 'addressLocality', 'postalCode', 'addressCountry') as $k) {
                if (!isset($addr[$k]) || !citami_schema_filled($addr[$k])) $out[] = $label . '.address.' . $k;
            }
        }
    } elseif ($identity) {
        $need('name');
        $need('url');
    }
    if (in_array('faqpage', $lower, true)) {
        $items = isset($node['mainEntity']) ? $node['mainEntity'] : array();
        if (is_array($items) && !isset($items[0]) && !empty($items)) $items = array($items);
        if (!is_array($items) || empty($items)) $out[] = 'FAQPage.mainEntity';
        else {
            foreach (array_values($items) as $i => $q) {
                if (!is_array($q) || !isset($q['name']) || !citami_schema_filled($q['name'])) $out[] = 'FAQPage.mainEntity[' . $i . '].name';
                $ans = (is_array($q) && isset($q['acceptedAnswer'])) ? citami_schema_first($q['acceptedAnswer']) : null;
                if (!is_array($ans) || !isset($ans['text']) || !citami_schema_filled($ans['text'])) $out[] = 'FAQPage.mainEntity[' . $i . '].acceptedAnswer.text';
            }
        }
    }
    if (in_array('product', $lower, true)) {
        $need('name');
        $offer = isset($node['offers']) ? citami_schema_first($node['offers']) : null;
        if (!is_array($offer)) $out[] = 'Product.offers';
        else {
            $has_price = (isset($offer['price']) && citami_schema_filled($offer['price'])) || (isset($offer['lowPrice']) && citami_schema_filled($offer['lowPrice']));
            if (!$has_price) $out[] = 'Product.offers.price';
            if (!isset($offer['priceCurrency']) || !citami_schema_filled($offer['priceCurrency'])) $out[] = 'Product.offers.priceCurrency';
        }
    }
    if (array_intersect(array('article', 'blogposting', 'newsarticle'), $lower)) {
        $need('headline');
        $need('author');
    }
    if (in_array('person', $lower, true)) $need('name');
    if (in_array('website', $lower, true)) {
        $need('name');
        $need('url');
    }
    if (in_array('event', $lower, true)) {
        $need('name');
        $need('startDate');
        $need('location');
    }
    if (in_array('breadcrumblist', $lower, true)) {
        $items = isset($node['itemListElement']) && is_array($node['itemListElement']) ? $node['itemListElement'] : array();
        if (empty($items)) $out[] = 'BreadcrumbList.itemListElement';
        foreach (array_values($items) as $i => $it) {
            $name_ok = is_array($it) && ((isset($it['name']) && citami_schema_filled($it['name'])) || (isset($it['item']['name']) && citami_schema_filled($it['item']['name'])));
            if (!$name_ok) $out[] = 'BreadcrumbList.itemListElement[' . $i . '].name';
        }
    }
}

/**
 * Per-site rate limit on inbound fix applications. Prevents a compromised
 * Citami backend (or a bug in the fix-generator) from flooding wp_head
 * with hundreds of injections in seconds.
 *
 * Returns true if the call may proceed, false if rate-limited.
 */
function citami_check_apply_rate() {
    $last = (int) get_option(CITAMI_FIX_APPLY_LAST_OPT, 0);
    $now  = time();
    if ($last > 0 && ($now - $last) < CITAMI_FIX_APPLY_INTERVAL) {
        return false;
    }
    update_option(CITAMI_FIX_APPLY_LAST_OPT, $now, false);
    return true;
}

/**
 * Checks the X-Citami-Key header against the stored key.
 * Used to authenticate inbound calls from Citami (fix application).
 */
function citami_check_permission(WP_REST_Request $request) {
    $expected = citami_get_api_key();
    if (empty($expected)) {
        return new WP_Error(
            'citami_not_configured',
            citami_brand_text('Citami API key non configurata.'),
            array('status' => 401)
        );
    }
    $provided = $request->get_header('x-citami-key');
    if (empty($provided) || !hash_equals($expected, $provided)) {
        return new WP_Error(
            'citami_bad_key',
            'API key non valida.',
            array('status' => 401)
        );
    }
    return true;
}

/**
 * v2.4.0 — PAGE-TARGETED SCHEMA. Pre-v2.4 ogni JSON-LD veniva stampato
 * su TUTTE le pagine (wp_head senza guardia): Organization duplicato
 * ovunque, FAQPage sulla pagina sbagliata. Ora ogni blocco ha un
 * target derivato dal @type e viene stampato solo dove serve:
 *   - AboutPage            → pagina chi-siamo/about
 *   - FAQPage              → pagina FAQ
 *   - tutto il resto       → homepage
 * I payload con @graph vengono spacchettati: un unico fix puo'
 * consegnare Organization (home) + AboutPage (about) in un colpo solo.
 */
function citami_schema_target($decoded) {
    $type = isset($decoded['@type']) ? $decoded['@type'] : '';
    if (is_array($type)) {
        $type = implode(' ', array_filter($type, 'is_string'));
    }
    if (!is_string($type)) $type = '';
    if (stripos($type, 'AboutPage') !== false) return 'about';
    if (stripos($type, 'FAQPage') !== false)   return 'faq';
    return 'home';
}

/** Default hardcoded (pre-v2.11 behaviour) — sempre attivi. */
function citami_default_about_slugs() {
    return array(
        'about', 'about-us', 'aboutus', 'about-me',
        'chi-siamo', 'chi_siamo', 'chisiamo',
        'la-nostra-storia', 'azienda', 'storia', 'il-nostro-team',
        'our-story', 'who-we-are', 'company',
        // 2.73 — German sites.
        'ueber-uns', 'uber-uns', 'ueberuns', 'unternehmen', 'wir-ueber-uns', 'team', 'unsere-geschichte',
    );
}

function citami_default_faq_slugs() {
    return array(
        'faq', 'faqs', 'domande-frequenti', 'domande',
        'frequently-asked-questions', 'help', 'aiuto',
        // 2.73 — German sites.
        'haeufige-fragen', 'haufige-fragen', 'fragen-und-antworten', 'hilfe',
    );
}

/**
 * v2.11.0 — parse di una lista comma-separated di slug: trim,
 * lowercase, sanitize_title su ogni voce, vuoti scartati, dedup.
 */
function citami_parse_slug_list($value) {
    $out = array();
    foreach (explode(',', (string) $value) as $part) {
        $slug = sanitize_title(strtolower(trim($part)));
        if ($slug === '') continue;
        $out[] = $slug;
    }
    return array_values(array_unique($out));
}

/** Sanitize-callback delle opzioni slug: normalizza e ricompone. */
function citami_sanitize_slug_list($value) {
    return implode(', ', citami_parse_slug_list($value));
}

/**
 * v2.11.1 — matcher titolo→keyword per l'auto-rilevamento slug.
 * Pre-2.11.1 bastava un substring match ovunque nel titolo: "What
 * clients say about us" (testimonial) diventava una pagina About e si
 * beccava lo schema AboutPage. Regole strette:
 *   - match se il titolo normalizzato INIZIA con la keyword, oppure
 *   - titolo corto (≤ 40 caratteri) che contiene la keyword come
 *     PAROLA INTERA — ma solo per keyword "specifiche" ($contains):
 *     'about' da solo resta prefix-only, è troppo comune a metà frase
 *     inglese (say about, more about, ...).
 */
function citami_title_matches_keyword($title, $keyword, $contains) {
    if (strpos($title, $keyword) === 0) {
        return true;
    }
    if (!$contains) {
        return false;
    }
    $len = function_exists('mb_strlen') ? mb_strlen($title) : strlen($title);
    if ($len > 40) {
        return false;
    }
    // Parola intera: la keyword non deve essere incollata a lettere/cifre.
    $re = '/(?<![a-z0-9])' . preg_quote($keyword, '/') . '(?![a-z0-9])/u';
    return (bool) preg_match($re, $title);
}

/**
 * v2.11.0 — auto-rilevamento slug dalle pagine WP pubblicate: se il
 * TITOLO di una pagina indica "chi siamo"/"about" o "faq"/"domande
 * frequenti", il suo slug reale entra nel set about/faq anche se non
 * è nei default né nelle opzioni. Cache in transient (1h) così il
 * costo di get_pages() non grava su ogni render.
 *
 * v2.11.1 — due fix dall'adversarial QA:
 *   - il match sui titoli è stretto (citami_title_matches_keyword):
 *     niente più substring a metà frase;
 *   - la scansione titoli è cappata a 100 pagine (alfabetico): su un
 *     sito da 500 pagine gli slug standard oltre il cap non venivano
 *     mai visti. Complemento: lookup diretto get_page_by_path per ogni
 *     slug DEFAULT — costo costante, copre siti di qualunque taglia
 *     per gli slug standard. Entrambi cacheati nello stesso transient.
 */
function citami_detect_page_slugs() {
    $cached = get_transient(CITAMI_DETECTED_SLUGS_TRANSIENT);
    if (is_array($cached) && isset($cached['about'], $cached['faq'])
        && is_array($cached['about']) && is_array($cached['faq'])) {
        return $cached;
    }
    $detected = array('about' => array(), 'faq' => array());
    // Keyword → regole: 'contains' = ammesso il match parola-intera su
    // titoli corti; false = solo prefisso.
    $about_keywords = array(
        'chi siamo' => true,
        'about'     => false,
    );
    $faq_keywords = array(
        'faq'               => true,
        'domande frequenti' => true,
    );
    $pages = get_pages(array('number' => 100)); // solo pubblicate (default)
    if (is_array($pages)) {
        foreach ($pages as $pg) {
            $title = strtolower(wp_strip_all_tags((string) $pg->post_title));
            $slug  = sanitize_title((string) $pg->post_name);
            if ($slug === '' || $title === '') continue;
            foreach ($about_keywords as $kw => $contains) {
                if (citami_title_matches_keyword($title, $kw, $contains)) {
                    $detected['about'][] = $slug;
                    break;
                }
            }
            foreach ($faq_keywords as $kw => $contains) {
                if (citami_title_matches_keyword($title, $kw, $contains)) {
                    $detected['faq'][] = $slug;
                    break;
                }
            }
        }
    }
    // Lookup diretto per gli slug default: get_page_by_path è una query
    // puntuale, indipendente dal numero di pagine del sito.
    foreach (citami_default_about_slugs() as $slug) {
        $pg = get_page_by_path($slug);
        if ($pg && isset($pg->post_status) && $pg->post_status === 'publish') {
            $detected['about'][] = sanitize_title((string) $pg->post_name);
        }
    }
    foreach (citami_default_faq_slugs() as $slug) {
        $pg = get_page_by_path($slug);
        if ($pg && isset($pg->post_status) && $pg->post_status === 'publish') {
            $detected['faq'][] = sanitize_title((string) $pg->post_name);
        }
    }
    $detected['about'] = array_values(array_unique($detected['about']));
    $detected['faq']   = array_values(array_unique($detected['faq']));
    set_transient(CITAMI_DETECTED_SLUGS_TRANSIENT, $detected, HOUR_IN_SECONDS);
    return $detected;
}

/**
 * Set completo degli slug about: default hardcoded ∪ opzione admin ∪
 * auto-rilevati. Le opzioni AGGIUNGONO, mai sostituiscono: con opzioni
 * vuote il comportamento è identico a pre-v2.11.
 */
function citami_about_page_slugs() {
    $detected = citami_detect_page_slugs();
    return array_values(array_unique(array_merge(
        citami_default_about_slugs(),
        citami_parse_slug_list(get_option(CITAMI_ABOUT_SLUGS_OPT, '')),
        $detected['about']
    )));
}

function citami_faq_page_slugs() {
    $detected = citami_detect_page_slugs();
    return array_values(array_unique(array_merge(
        citami_default_faq_slugs(),
        citami_parse_slug_list(get_option(CITAMI_FAQ_SLUGS_OPT, '')),
        $detected['faq']
    )));
}

function citami_is_about_page() {
    if (!is_page()) return false;
    $post = get_post();
    if (!$post) return false;
    $slug = (string) $post->post_name;
    return in_array($slug, citami_about_page_slugs(), true);
}

function citami_is_faq_page() {
    if (!is_page()) return false;
    $post = get_post();
    if (!$post) return false;
    $slug = (string) $post->post_name;
    return in_array($slug, citami_faq_page_slugs(), true);
}

/**
 * Targets ammessi sulla request corrente. Stringa vuota '' = blocchi
 * legacy pre-v2.4 senza campo target: vengono trattati come 'home'
 * (corregge la stampa site-wide indiscriminata delle versioni vecchie).
 */
function citami_current_schema_targets() {
    if (is_front_page() || is_home()) return array('home', '');
    if (citami_is_about_page())       return array('about');
    if (citami_is_faq_page())         return array('faq');
    return array();
}

/**
 * Validates that $content is a JSON-LD payload with a Schema.org @context.
 * Returns the safely-re-encoded JSON string on success, or false on
 * failure. Re-encoding strips any unsafe characters that survived a naive
 * concatenation upstream and makes the output deterministic.
 */
function citami_validate_jsonld($content) {
    $content = trim((string) $content);
    if ($content === '') return false;
    // If a caller wraps the JSON in <script> tags, strip them — we re-add
    // a clean wrapper at echo time. 2.65 — several <script> blocks (the
    // platform keeps every valid block of a fix) become one @graph
    // instead of failing to decode.
    if (stripos($content, '<script') !== false) {
        if (!preg_match_all('#<script[^>]*>(.*?)</script>#is', $content, $m) || empty($m[1])) return false;
        if (count($m[1]) === 1) {
            $content = trim($m[1][0]);
        } else {
            $nodes = array();
            foreach ($m[1] as $body) {
                $one = json_decode(trim($body), true);
                if (!is_array($one)) return false;
                if (isset($one['@graph']) && is_array($one['@graph'])) {
                    foreach ($one['@graph'] as $n) $nodes[] = $n;
                } elseif (isset($one[0])) {
                    foreach ($one as $n) $nodes[] = $n;
                } else {
                    unset($one['@context']);
                    $nodes[] = $one;
                }
            }
            $content = wp_json_encode(array('@context' => 'https://schema.org', '@graph' => $nodes));
            if (!is_string($content)) return false;
        }
    }
    $decoded = json_decode($content, true);
    if ($decoded === null && json_last_error() !== JSON_ERROR_NONE) {
        return false;
    }
    if (!is_array($decoded)) return false;
    // @context check — Schema.org markup must declare it. Accept either a
    // string ("https://schema.org") or an array of contexts.
    $ctx = isset($decoded['@context']) ? $decoded['@context'] : null;
    $has_schema_org = false;
    if (is_string($ctx) && stripos($ctx, 'schema.org') !== false) {
        $has_schema_org = true;
    } elseif (is_array($ctx)) {
        foreach ($ctx as $c) {
            if (is_string($c) && stripos($c, 'schema.org') !== false) {
                $has_schema_org = true;
                break;
            }
        }
    }
    if (!$has_schema_org) return false;
    // v2.11.1 — JSON_HEX_TAG: '<' e '>' diventano </>, così un
    // testo libero del cliente che contiene "</script>" (descrizione
    // offerta, nome, ...) non può chiudere il tag <script> in cui il
    // blocco viene stampato. Il JSON resta semanticamente identico.
    $safe = wp_json_encode(
        $decoded,
        JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE | JSON_HEX_TAG
    );
    return is_string($safe) ? $safe : false;
}

/**
 * v2.11.0 — memorizza un payload schema GIÀ validato da
 * citami_validate_jsonld, spacchettando eventuali @graph in blocchi
 * per-target (v2.4.0). Estratto da citami_rest_apply_fix così anche il
 * percorso Approva della coda review (citami_apply_queued_fix) instrada
 * per pagina invece di parcheggiare l'intero @graph sulla home.
 *
 * Robustezza @graph (pinnata nei test): nodi non-array vengono saltati;
 * nodi senza @type (o con @type sconosciuto: Person, Menu, ...) vanno
 * alla home via citami_schema_target — mai un crash, mai un drop
 * silenzioso di un nodo array valido.
 *
 * Ritorna il numero di blocchi memorizzati.
 *
 * v2.11.1 — semantica REPLACE-AT-FIX-LEVEL: prima di memorizzare, tutti
 * i blocchi con lo stesso titolo fix (qualunque target, inclusi i
 * legacy '') vengono eliminati. Poi i nuovi nodi vengono appesi SENZA
 * dedup tra loro. Vedi citami_purge_head_blocks_by_title.
 */
function citami_store_schema_payload($title, $safe_json) {
    citami_purge_head_blocks_by_title(CITAMI_SCHEMA_OPT, $title);
    $decoded = json_decode($safe_json, true);
    $graph = (is_array($decoded) && isset($decoded['@graph']) && is_array($decoded['@graph']))
        ? $decoded['@graph']
        : null;
    if ($graph !== null) {
        $ctx = isset($decoded['@context']) ? $decoded['@context'] : 'https://schema.org';
        $stored = 0;
        foreach ($graph as $node) {
            if (!is_array($node)) continue;
            if (!isset($node['@context'])) {
                $node = array_merge(array('@context' => $ctx), $node);
            }
            $node_json = wp_json_encode($node, JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE | JSON_HEX_TAG);
            if (!is_string($node_json)) continue;
            citami_append_head_block(CITAMI_SCHEMA_OPT, $title, $node_json, citami_schema_target($node));
            $stored++;
        }
        return $stored;
    }
    citami_append_head_block(CITAMI_SCHEMA_OPT, $title, $safe_json, citami_schema_target(is_array($decoded) ? $decoded : array()));
    return 1;
}

/**
 * v2.12.0 — ONDA-2 FAQ ONE-CLICK. Il fix faq_page cadeva nel default
 * "revisione manuale": la piattaforma lo marcava applied e il verify-bot
 * 24h dopo non trovava nulla → verification_failed garantito. Ora
 * l'apply crea una VERA pagina FAQ: contenuto VISIBILE (blocchi
 * Gutenberg dalle coppie domanda/risposta del JSON-LD) + schema
 * instradato sulla pagina — mai markup "fantasma" (dal 2026 AI Mode
 * verifica lo schema FAQPage contro il contenuto visibile).
 *
 * Regole:
 *  - la pagina viene PUBBLICATA: il click su "Applica" in dashboard è
 *    la conferma del cliente (il contenuto era nel preview della card);
 *  - se esiste già una NOSTRA pagina (meta _citami_faq_page) si
 *    aggiorna il contenuto;
 *  - se esiste una pagina FAQ DEL CLIENTE (slug default) NON si tocca
 *    il suo contenuto: solo schema + messaggio esplicito;
 *  - NO auto-apply: questa routine gira solo su azione esplicita
 *    (bottone Applica / Approva in coda), mai dal cron auto-push.
 */
function citami_faq_pairs_from_jsonld($safe_json) {
    $decoded = json_decode($safe_json, true);
    if (!is_array($decoded)) return array();
    $node = $decoded;
    if (isset($decoded['@graph']) && is_array($decoded['@graph'])) {
        $node = null;
        foreach ($decoded['@graph'] as $candidate) {
            if (is_array($candidate) && citami_schema_target($candidate) === 'faq') {
                $node = $candidate;
                break;
            }
        }
        if ($node === null) return array();
    }
    $entities = isset($node['mainEntity']) && is_array($node['mainEntity'])
        ? $node['mainEntity']
        : array();
    $pairs = array();
    foreach ($entities as $entity) {
        if (!is_array($entity)) continue;
        $q = isset($entity['name']) && is_string($entity['name']) ? trim($entity['name']) : '';
        $a = '';
        if (isset($entity['acceptedAnswer'])) {
            $answer = $entity['acceptedAnswer'];
            if (is_array($answer) && isset($answer['text']) && is_string($answer['text'])) {
                $a = trim($answer['text']);
            }
        }
        if ($q === '' || $a === '') continue;
        $pairs[] = array('q' => $q, 'a' => $a);
    }
    return $pairs;
}

function citami_faq_page_content(array $pairs) {
    $blocks = array();
    foreach ($pairs as $pair) {
        $q = esc_html(wp_strip_all_tags($pair['q']));
        $a = wp_kses_post($pair['a']);
        $blocks[] = "<!-- wp:heading {\"level\":3} -->\n<h3 class=\"wp-block-heading\">{$q}</h3>\n<!-- /wp:heading -->";
        $blocks[] = "<!-- wp:paragraph -->\n<p>{$a}</p>\n<!-- /wp:paragraph -->";
    }
    return implode("\n\n", $blocks);
}

function citami_apply_faq_page($title, $code, $fix_id = '') {
    $safe_json = citami_validate_jsonld($code);
    if ($safe_json === false) {
        return array(
            'ok'      => false,
            'message' => citami_t('JSON-LD FAQPage non valido.', 'Invalid FAQPage JSON-LD.'),
        );
    }
    // 2.65 — a public FAQ page is never published with empty answers or placeholders.
    $missing = citami_schema_missing($safe_json);
    if (!empty($missing)) {
        return array(
            'ok'      => false,
            'message' => citami_t('FAQ incompleta, non pubblicata. Mancano: ', 'Incomplete FAQ, not published. Missing: ') . implode(', ', array_slice($missing, 0, 6)),
        );
    }
    $pairs = citami_faq_pairs_from_jsonld($safe_json);
    if (empty($pairs)) {
        return array(
            'ok'      => false,
            'message' => citami_t('Nessuna coppia domanda/risposta nel JSON-LD FAQPage.', 'No question/answer pairs in the FAQPage JSON-LD.'),
        );
    }

    // 1) La NOSTRA pagina, se già creata in un apply precedente.
    $ours = get_posts(array(
        'post_type'   => 'page',
        'post_status' => array('publish', 'draft'),
        'meta_key'    => '_citami_faq_page', // phpcs:ignore WordPress.DB.SlowDBQuery.slow_db_query_meta_key -- one flag on at most a handful of pages
        'meta_value'  => '1', // phpcs:ignore WordPress.DB.SlowDBQuery.slow_db_query_meta_value
        'numberposts' => 1,
    ));

    // 2) Una pagina FAQ del CLIENTE (slug default, pubblicata).
    $user_page = null;
    if (empty($ours)) {
        foreach (citami_default_faq_slugs() as $slug) {
            $pg = get_page_by_path($slug);
            if ($pg && $pg->post_status === 'publish') {
                $user_page = $pg;
                break;
            }
        }
    }

    // 2.66 — the page this fix would write is excluded in the dashboard.
    $target_page = !empty($ours) ? $ours[0] : $user_page;
    $target_path = $target_page ? (string) wp_parse_url((string) get_permalink($target_page), PHP_URL_PATH) : '/faq/';
    if (citami_path_is_excluded($target_path)) {
        return array(
            'ok'      => false,
            'message' => citami_t('La pagina FAQ è tra le pagine escluse nelle impostazioni Citami: non è stata toccata.', 'The FAQ page is among the pages excluded in the Citami settings: it was left untouched.'),
        );
    }

    if (!empty($ours)) {
        wp_update_post(array(
            'ID'           => $ours[0]->ID,
            'post_content' => citami_faq_page_content($pairs),
        ));
        if ($fix_id !== '') {
            update_post_meta($ours[0]->ID, '_citami_fix_id', (string) $fix_id);
        }
        citami_store_schema_payload($title, $safe_json);
        return array(
            'ok'      => true,
            'message' => citami_t('Pagina FAQ aggiornata (contenuto visibile + schema).', 'FAQ page updated (visible content + schema).'),
        );
    }

    if ($user_page !== null) {
        // Mai sovrascrivere il contenuto del cliente: solo schema.
        citami_store_schema_payload($title, $safe_json);
        return array(
            'ok'      => true,
            'message' => citami_t(
                'Schema FAQPage aggiunto alla tua pagina FAQ esistente. Verifica che le domande dello schema compaiano anche come contenuto visibile della pagina.',
                'FAQPage schema added to your existing FAQ page. Make sure the schema questions also appear as visible content on the page.'
            ),
        );
    }

    $page_id = wp_insert_post(array(
        'post_type'    => 'page',
        'post_status'  => 'publish',
        'post_title'   => citami_t('Domande frequenti', 'Frequently asked questions'),
        'post_name'    => 'faq',
        'post_content' => citami_faq_page_content($pairs),
    ), true);
    if (is_wp_error($page_id) || !$page_id) {
        return array(
            'ok'      => false,
            'message' => citami_t('Creazione della pagina FAQ non riuscita.', 'Could not create the FAQ page.'),
        );
    }
    update_post_meta($page_id, '_citami_faq_page', '1');
    if ($fix_id !== '') {
        update_post_meta($page_id, '_citami_fix_id', (string) $fix_id);
    }
    // Il router schema deve vedere la pagina appena creata.
    delete_transient(CITAMI_DETECTED_SLUGS_TRANSIENT);
    citami_store_schema_payload($title, $safe_json);
    return array(
        'ok'      => true,
        'message' => citami_t(
            'Pagina "Domande frequenti" creata e pubblicata: contenuto visibile + schema FAQPage.',
            '"Frequently asked questions" page created and published: visible content + FAQPage schema.'
        ),
    );
}

/**
 * Allowed attributes for meta_tags injection. Only the attributes a real
 * <meta> tag uses — everything else (id, class, style, onclick, …) is
 * stripped by wp_kses.
 */
function citami_meta_kses_allowlist() {
    return array(
        'meta' => array(
            'name'       => true,
            'content'    => true,
            'property'   => true,
            'http-equiv' => true,
            'charset'    => true,
            'scheme'     => true,
        ),
    );
}

/* ────────────────────────────────────────────────────────────────── */
/*  2.31.1 — PAGE BUILDERS                                             */
/*  Elementor keeps the page in _elementor_data and leaves            */
/*  post_content empty (or a flat text copy); Divi and WPBakery wrap  */
/*  the text in shortcodes that strip_shortcodes() deletes whole.     */
/*  Everything that READS a post's content (AEO score, automatic      */
/*  description, internal-link index, wordCount, truth scan) goes     */
/*  through this helper, which rebuilds plain HTML from the builder   */
/*  data. Filterable so other builders can plug in.                   */
/* ────────────────────────────────────────────────────────────────── */

/** HTML of a post as a reader would see it: post_content, or the builder's data turned into plain HTML. */
function citami_post_content_html($post) {
    if (is_numeric($post)) {
        $post = get_post((int) $post);
    }
    if (!is_object($post)) {
        return '';
    }
    $content = isset($post->post_content) ? (string) $post->post_content : '';
    if (empty($post->ID)) {
        return $content; // an unsaved post object: nothing to look up
    }
    $html = null;
    if (get_post_meta($post->ID, '_elementor_edit_mode', true) === 'builder') {
        $raw = get_post_meta($post->ID, '_elementor_data', true);
        $tree = is_string($raw) && $raw !== '' ? json_decode($raw, true) : (is_array($raw) ? $raw : null);
        if (is_array($tree)) {
            $built = citami_elementor_tree_html($tree);
            if (trim($built) !== '') {
                $html = $built;
            }
        }
    }
    if ($html === null && preg_match('/\[(et_pb_|vc_|fusion_)/', $content)) {
        // Divi / WPBakery / Avada: keep the inner text, drop the wrappers.
        $html = preg_replace('/\[\/?(?:et_pb_|vc_|fusion_)[a-z0-9_]*(?:\s[^\]]*)?\]/i', "\n", $content);
    }
    if ($html === null) {
        $html = $content;
    }
    return (string) apply_filters('citami_post_content_html', $html, $post, $content);
}

/** Elementor element tree → HTML (headings, text, lists, images, FAQ-like accordions, buttons, raw HTML). Recursive. */
function citami_elementor_tree_html($elements) {
    $out = '';
    foreach ((array) $elements as $el) {
        if (!is_array($el)) {
            continue;
        }
        $s = isset($el['settings']) && is_array($el['settings']) ? $el['settings'] : array();
        $type = isset($el['widgetType']) ? (string) $el['widgetType'] : '';
        $str = function ($key) use ($s) { return isset($s[$key]) && is_scalar($s[$key]) ? (string) $s[$key] : ''; };
        switch ($type) {
            case 'heading':
            case 'animated-headline':
                $tag = preg_match('/^h[1-6]$/', $str('header_size')) ? $str('header_size') : 'h2';
                $title = $str('title') !== '' ? $str('title') : trim($str('before_text') . ' ' . $str('highlighted_text') . ' ' . $str('after_text'));
                if ($title !== '') $out .= "<$tag>" . $title . "</$tag>\n";
                break;
            case 'text-editor':
            case 'theme-post-content':
                $out .= $str('editor') . "\n";
                break;
            case 'html':
            case 'shortcode':
                $out .= $str('html') . $str('shortcode') . "\n";
                break;
            case 'image':
            case 'theme-post-featured-image':
                if (isset($s['image']) && is_array($s['image'])) {
                    $id = isset($s['image']['id']) ? (int) $s['image']['id'] : 0;
                    $alt = $id ? (string) get_post_meta($id, '_wp_attachment_image_alt', true) : '';
                    $url = isset($s['image']['url']) ? (string) $s['image']['url'] : '';
                    if ($url !== '') $out .= '<img src="' . esc_url($url) . '" alt="' . esc_attr($alt) . '">' . "\n";
                }
                if ($str('caption') !== '') $out .= '<p>' . $str('caption') . "</p>\n";
                break;
            case 'icon-list':
            case 'price-list':
                $items = isset($s['icon_list']) ? $s['icon_list'] : (isset($s['price_list']) ? $s['price_list'] : array());
                if (is_array($items) && $items) {
                    $out .= "<ul>\n";
                    foreach ($items as $it) {
                        if (!is_array($it)) continue;
                        $line = trim(implode(' ', array_filter(array(isset($it['text']) ? $it['text'] : '', isset($it['title']) ? $it['title'] : '', isset($it['item_description']) ? $it['item_description'] : '', isset($it['price']) ? $it['price'] : ''))));
                        if ($line !== '') $out .= '<li>' . $line . "</li>\n";
                    }
                    $out .= "</ul>\n";
                }
                break;
            case 'accordion':
            case 'toggle':
            case 'nested-accordion':
            case 'tabs':
            case 'nested-tabs':
                $tabs = isset($s['tabs']) ? $s['tabs'] : (isset($s['items']) ? $s['items'] : array());
                foreach ((array) $tabs as $t) {
                    if (!is_array($t)) continue;
                    $title = isset($t['tab_title']) ? $t['tab_title'] : (isset($t['item_title']) ? $t['item_title'] : '');
                    $body = isset($t['tab_content']) ? $t['tab_content'] : '';
                    if ($title !== '') $out .= '<h3>' . $title . "</h3>\n";
                    if ($body !== '') $out .= $body . "\n";
                }
                break;
            case 'button':
                if ($str('text') !== '') {
                    $href = isset($s['link']['url']) ? (string) $s['link']['url'] : '';
                    $out .= ($href !== '' ? '<a href="' . esc_url($href) . '">' . $str('text') . '</a>' : $str('text')) . "\n";
                }
                break;
            case 'call-to-action':
            case 'icon-box':
            case 'image-box':
            case 'flip-box':
            case 'testimonial':
            case 'blockquote':
            case 'alert':
                foreach (array('title', 'title_text', 'description', 'description_text', 'testimonial_content', 'blockquote_content', 'alert_title', 'alert_description', 'title_text_a', 'description_text_a') as $k) {
                    if ($str($k) !== '') $out .= '<p>' . $str($k) . "</p>\n";
                }
                break;
            case 'counter':
                if ($str('title') !== '') $out .= '<p>' . trim($str('prefix') . $str('ending_number') . $str('suffix') . ' ' . $str('title')) . "</p>\n";
                break;
            default:
                break;
        }
        if (!empty($el['elements']) && is_array($el['elements'])) {
            $out .= citami_elementor_tree_html($el['elements']);
        }
    }
    return $out;
}

/* ────────────────────────────────────────────────────────────────── */
/*  2.31.1 — PAGE CACHES                                               */
/*  Seen with WP Rocket on the test site: a fix changes the meta of a */
/*  page, the cache plugin knows nothing about it (no save_post) and  */
/*  keeps serving the old HTML until its lifetime expires; the verify */
/*  bot then reads the old page. Every change that alters what a page */
/*  outputs purges it here, through the public API of each cache      */
/*  plugin. No plugin present → no-op.                                 */
/* ────────────────────────────────────────────────────────────────── */

/** Purge one post's cached page, or (null) the whole site cache. Never throws. */
function citami_purge_cache($post_id = null) {
    $post_id = $post_id === null ? null : (int) $post_id;
    // One site-wide purge per request is plenty (a global so tests can reset it).
    if ($post_id === null && !empty($GLOBALS['citami_purged_all'])) {
        return;
    }
    if ($post_id === null) {
        $GLOBALS['citami_purged_all'] = true;
    }
    try {
        // WP Rocket
        if ($post_id && function_exists('rocket_clean_post')) {
            rocket_clean_post($post_id);
        } elseif (function_exists('rocket_clean_domain')) {
            rocket_clean_domain();
        }
        // W3 Total Cache
        if ($post_id && function_exists('w3tc_flush_post')) {
            w3tc_flush_post($post_id);
        } elseif (function_exists('w3tc_flush_all')) {
            w3tc_flush_all();
        }
        // WP Super Cache
        if ($post_id && function_exists('wp_cache_post_change')) {
            wp_cache_post_change($post_id);
        } elseif (function_exists('wp_cache_clear_cache')) {
            wp_cache_clear_cache();
        }
        // LiteSpeed Cache
        if ($post_id) {
            do_action('litespeed_purge_post', $post_id); // phpcs:ignore WordPress.NamingConventions.PrefixAllGlobals.NonPrefixedHooknameFound -- LiteSpeed Cache's own hook
        } else {
            do_action('litespeed_purge_all'); // phpcs:ignore WordPress.NamingConventions.PrefixAllGlobals.NonPrefixedHooknameFound -- LiteSpeed Cache's own hook
        }
        // WP Fastest Cache
        if (isset($GLOBALS['wp_fastest_cache']) && is_object($GLOBALS['wp_fastest_cache'])) {
            if ($post_id && method_exists($GLOBALS['wp_fastest_cache'], 'singleDeleteCache')) {
                $GLOBALS['wp_fastest_cache']->singleDeleteCache(false, $post_id);
            } elseif (method_exists($GLOBALS['wp_fastest_cache'], 'deleteCache')) {
                $GLOBALS['wp_fastest_cache']->deleteCache(true);
            }
        }
        // Cache Enabler, SiteGround, Breeze, Hummingbird, Autoptimize, Kinsta, Cloudways/Varnish
        if ($post_id) {
            do_action('cache_enabler_clear_page_cache_by_post_id', $post_id); // phpcs:ignore WordPress.NamingConventions.PrefixAllGlobals.NonPrefixedHooknameFound -- Cache Enabler's own hook
        } else {
            do_action('cache_enabler_clear_complete_cache'); // phpcs:ignore WordPress.NamingConventions.PrefixAllGlobals.NonPrefixedHooknameFound -- Cache Enabler's own hook
        }
        do_action('sg_cachepress_purge_cache', $post_id ? get_permalink($post_id) : ''); // phpcs:ignore WordPress.NamingConventions.PrefixAllGlobals.NonPrefixedHooknameFound -- SiteGround Optimizer's own hook
        do_action('breeze_clear_all_cache'); // phpcs:ignore WordPress.NamingConventions.PrefixAllGlobals.NonPrefixedHooknameFound -- Breeze's own hook
        do_action('wphb_clear_page_cache'); // phpcs:ignore WordPress.NamingConventions.PrefixAllGlobals.NonPrefixedHooknameFound -- Hummingbird's own hook
        if (class_exists('autoptimizeCache') && method_exists('autoptimizeCache', 'clearall')) {
            autoptimizeCache::clearall();
        }
        // Object/page cache drop-ins that honour the core hook.
        if ($post_id && function_exists('clean_post_cache')) {
            clean_post_cache($post_id);
        }
        do_action('citami_cache_purged', $post_id);
    } catch (\Throwable $e) {
        citami_debug_log('[citami] cache purge skipped: ' . $e->getMessage());
    }
}

/** Purge the pages the plugin serves itself (/ai-info, its documents, llms.txt). */
function citami_purge_virtual_pages() {
    $urls = array();
    if (function_exists('citami_truth_ai_info_url')) {
        $urls[] = citami_truth_ai_info_url();
        if (function_exists('citami_brand_docs')) {
            foreach (citami_brand_docs() as $d) {
                $urls[] = citami_brand_doc_url($d['slug']);
            }
        }
    }
    $urls[] = home_url('/llms.txt');
    if (function_exists('rocket_clean_files')) {
        try {
            rocket_clean_files($urls);
        } catch (\Throwable $e) {
            citami_debug_log('[citami] cache purge skipped: ' . $e->getMessage());
        }
    } else {
        citami_purge_cache(null);
    }
}

// Per-page meta: citami_seo_save_post_fields() purges the page itself
// (editor, bulk edit, importer and platform fixes all go through it).

// Options that change what pages output → whole site. Logs, queues,
// indexes, scans and keys are excluded: they change on every request.
add_action('updated_option', function ($option) {
    $option = (string) $option;
    if (strpos($option, 'citami_') !== 0) {
        return;
    }
    if (preg_match('/(log|queue|index|scan|stats|cache|version|_key$|_health|fixes|gsc|ranges|_last|_ts$|_state$)/', $option)) {
        return;
    }
    if ($option === CITAMI_TRUTH_OPT || (defined('CITAMI_BRAND_DOCS_OPT') && $option === CITAMI_BRAND_DOCS_OPT)) {
        citami_purge_virtual_pages();
        return;
    }
    citami_purge_cache(null);
}, 10, 1);


/* ────────────────────────────────────────────────────────────────── */
/*  2.36 — BRAND (Citami for citami.ai, Citeproof for citeproof.co)     */
/* ────────────────────────────────────────────────────────────────── */

/** 'citami' | 'citeproof' (constant from the build, filterable for tests). */
function citami_brand() {
    $b = (string) apply_filters('citami_brand', defined('CITAMI_BRAND') ? CITAMI_BRAND : 'citami');
    // WPORG-2 — the WordPress.org build ships with 'auto': Citami (citami.ai)
    // on sites in Italian, CiteProof (citeproof.co) everywhere else.
    if ($b === 'auto') {
        $locale = function_exists('get_locale') ? (string) get_locale() : '';
        return stripos($locale, 'it') === 0 ? 'citami' : 'citeproof';
    }
    return $b === 'citeproof' ? 'citeproof' : 'citami';
}

function citami_brand_name() {
    return citami_brand() === 'citeproof' ? 'CiteProof' : 'Citami';
}

/** Platform address of the active brand (the Settings field overrides it). */
function citami_default_endpoint() {
    return citami_brand() === 'citeproof' ? 'https://citeproof.co' : 'https://citami.ai';
}

function citami_brand_product() {
    // WPORG-1 — the product is "Citami" ("CiteProof" in the US build); the
    // directory name adds what it does ("– AI SEO & GEO for AI Visibility").
    return citami_brand_name();
}

/** Plugin slug = folder name of the build. */
function citami_brand_slug() {
    return citami_brand() === 'citeproof' ? 'citeproof-connector' : 'citami-connector';
}

function citami_brand_site() {
    return citami_brand() === 'citeproof' ? 'https://citeproof.co' : 'https://citami.ai';
}

function citami_brand_host() {
    return citami_brand() === 'citeproof' ? 'citeproof.co' : 'citami.ai';
}

/** Rewrites "Citami" copy for the other brand (applied by citami_t and to fixed labels). */
function citami_brand_text($text) {
    if (citami_brand() === 'citami') {
        return $text;
    }
    return str_replace(
        array('Citami.ai', 'citami.ai', 'Citami Connector', 'Citami'),
        array('CiteProof.co', 'citeproof.co', 'CiteProof', 'CiteProof'),
        (string) $text
    );
}

/* ────────────────────────────────────────────────────────────────── */
/*  WPORG-1 — output filtering for the plugin's own HTML builders.     */
/*                                                                     */
/*  Icons, cards, forms and rows are built by functions that escape    */
/*  every value they put in; printing them still goes through wp_kses  */
/*  with the tags and attributes this plugin uses (SVG icons, forms,   */
/*  data-* hooks for app.js), as the WordPress.org review requires.    */
/* ────────────────────────────────────────────────────────────────── */

/** Allowed tags/attributes for the plugin's admin and front-end markup. */
function citami_kses_allowed() {
    static $allowed = null;
    // The plugin's admin screens use CSS variables and rgba() in inline
    // styles; let wp_kses keep them there (admin requests only).
    if (is_admin() && !has_filter('safe_style_css', 'citami_kses_safe_style')) {
        add_filter('safe_style_css', 'citami_kses_safe_style');
        add_filter('safecss_filter_attr_allow_css', 'citami_kses_allow_css', 10, 2);
    }
    if ($allowed !== null) {
        return $allowed;
    }
    $global = array(
        'class' => true, 'id' => true, 'style' => true, 'title' => true, 'role' => true, 'hidden' => true,
        'tabindex' => true, 'lang' => true, 'dir' => true, 'data-*' => true,
        'aria-hidden' => true, 'aria-label' => true, 'aria-labelledby' => true, 'aria-describedby' => true,
        'aria-expanded' => true, 'aria-controls' => true, 'aria-current' => true, 'aria-live' => true,
        'aria-pressed' => true, 'aria-selected' => true, 'aria-valuenow' => true, 'aria-valuemin' => true, 'aria-valuemax' => true,
    );
    $allowed = wp_kses_allowed_html('post');
    $extra = array(
        'form'     => array('action' => true, 'method' => true, 'enctype' => true, 'target' => true, 'novalidate' => true, 'name' => true),
        'input'    => array('type' => true, 'name' => true, 'value' => true, 'checked' => true, 'disabled' => true, 'readonly' => true,
                            'placeholder' => true, 'min' => true, 'max' => true, 'step' => true, 'maxlength' => true, 'size' => true,
                            'required' => true, 'form' => true, 'autocomplete' => true, 'pattern' => true, 'accept' => true, 'list' => true, 'multiple' => true),
        'button'   => array('type' => true, 'name' => true, 'value' => true, 'disabled' => true, 'form' => true, 'formaction' => true),
        'select'   => array('name' => true, 'disabled' => true, 'multiple' => true, 'required' => true, 'form' => true, 'size' => true),
        'option'   => array('value' => true, 'selected' => true, 'disabled' => true, 'label' => true),
        'optgroup' => array('label' => true, 'disabled' => true),
        'textarea' => array('name' => true, 'rows' => true, 'cols' => true, 'disabled' => true, 'readonly' => true, 'placeholder' => true,
                            'maxlength' => true, 'required' => true, 'form' => true, 'spellcheck' => true),
        'label'    => array('for' => true),
        'fieldset' => array('disabled' => true), 'legend' => array(),
        'details'  => array('open' => true), 'summary' => array(),
        'meter'    => array('value' => true, 'min' => true, 'max' => true, 'low' => true, 'high' => true, 'optimum' => true),
        'progress' => array('value' => true, 'max' => true),
        'time'     => array('datetime' => true), 'output' => array('for' => true, 'name' => true),
        'svg'      => array('xmlns' => true, 'viewbox' => true, 'width' => true, 'height' => true, 'fill' => true, 'stroke' => true,
                            'stroke-width' => true, 'stroke-linecap' => true, 'stroke-linejoin' => true, 'focusable' => true, 'preserveaspectratio' => true),
        'g'        => array('fill' => true, 'stroke' => true, 'stroke-width' => true, 'transform' => true, 'opacity' => true),
        'path'     => array('d' => true, 'fill' => true, 'stroke' => true, 'stroke-width' => true, 'stroke-linecap' => true, 'stroke-linejoin' => true,
                            'stroke-dasharray' => true, 'stroke-dashoffset' => true, 'opacity' => true, 'fill-rule' => true, 'clip-rule' => true, 'transform' => true),
        'circle'   => array('cx' => true, 'cy' => true, 'r' => true, 'fill' => true, 'stroke' => true, 'stroke-width' => true,
                            'stroke-dasharray' => true, 'stroke-dashoffset' => true, 'stroke-linecap' => true, 'transform' => true, 'opacity' => true, 'pathlength' => true),
        'rect'     => array('x' => true, 'y' => true, 'width' => true, 'height' => true, 'rx' => true, 'ry' => true, 'fill' => true, 'stroke' => true, 'stroke-width' => true, 'opacity' => true),
        'line'     => array('x1' => true, 'y1' => true, 'x2' => true, 'y2' => true, 'stroke' => true, 'stroke-width' => true, 'stroke-linecap' => true, 'stroke-dasharray' => true),
        'polyline' => array('points' => true, 'fill' => true, 'stroke' => true, 'stroke-width' => true, 'stroke-linecap' => true, 'stroke-linejoin' => true),
        'polygon'  => array('points' => true, 'fill' => true, 'stroke' => true, 'stroke-width' => true),
        'text'     => array('x' => true, 'y' => true, 'dx' => true, 'dy' => true, 'text-anchor' => true, 'font-size' => true, 'font-weight' => true, 'fill' => true, 'dominant-baseline' => true),
        'tspan'    => array('x' => true, 'y' => true, 'dx' => true, 'dy' => true),
        'title'    => array(),
    );
    foreach ($extra as $tag => $attrs) {
        $allowed[$tag] = array_merge(isset($allowed[$tag]) ? $allowed[$tag] : array(), $attrs);
    }
    foreach ($allowed as $tag => $attrs) {
        $allowed[$tag] = array_merge(is_array($attrs) ? $attrs : array(), $global);
    }
    return $allowed;
}

/** CSS the plugin's inline styles use (custom properties, flex/grid). */
function citami_kses_safe_style($props) {
    return array_merge((array) $props, array(
        '--*', 'display', 'gap', 'row-gap', 'column-gap', 'align-items', 'align-self', 'justify-content', 'flex-wrap', 'flex',
        'flex-direction', 'grid-template-columns', 'grid-column', 'white-space', 'text-overflow', 'overflow', 'opacity',
        'position', 'top', 'left', 'right', 'bottom', 'z-index', 'transform', 'inset', 'cursor', 'vertical-align', 'word-break',
    ));
}

/** Colour and gradient functions are fine in the plugin's own styles. */
function citami_kses_allow_css($allow, $css_test_string) {
    if ($allow) {
        return $allow;
    }
    $rest = preg_replace('/\b(?:rgba?|hsla?|linear-gradient|radial-gradient|conic-gradient)\((?:[^()]|\((?:[^()])*\))*\)/i', '', (string) $css_test_string);
    return strpbrk((string) $rest, '\\(&}=@') === false && strpos((string) $rest, '/*') === false;
}

/** The plugin's own HTML, filtered for output. */
function citami_kses($html) {
    add_filter('safe_style_css', 'citami_kses_safe_style');
    add_filter('safecss_filter_attr_allow_css', 'citami_kses_allow_css', 10, 2);
    $out = wp_kses((string) $html, citami_kses_allowed());
    remove_filter('safe_style_css', 'citami_kses_safe_style');
    remove_filter('safecss_filter_attr_allow_css', 'citami_kses_allow_css', 10);
    return $out;
}


/** WPORG-1 — diagnostics only when the site runs with WP_DEBUG on. */
function citami_debug_log($message) {
    if (defined('WP_DEBUG') && WP_DEBUG) {
        error_log((string) $message); // phpcs:ignore WordPress.PHP.DevelopmentFunctions.error_log_error_log -- debug-mode diagnostics only.
    }
}


/** WPORG-1 — what connecting sends, shown next to every key field. */
function citami_connect_disclosure_html() {
    $privacy = citami_brand() === 'citeproof' ? 'https://citeproof.co/privacy' : 'https://citami.ai/privacy';
    return '<p class="description citami-connect-note">'
        . esc_html(citami_t(
            'Con la chiave il plugin invia alla piattaforma: indirizzo del sito e versione del plugin, le visite dei bot AI (user agent, pagina, ora), l\'esito dei fix applicati e un riepilogo dei contenuti (conteggi, titoli e indirizzi delle pagine, mai il testo). Il testo di una pagina parte solo quando chiedi una bozza AI. Senza chiave non parte nulla.',
            'With the key the plugin sends the platform: the site address and plugin version, AI bot visits (user agent, page, time), the result of applied fixes and a content summary (counts, page titles and addresses, never the text). A page\'s text is sent only when you ask for an AI draft. Without a key nothing is sent.'
        ))
        . ' <a href="' . esc_url($privacy) . '" target="_blank" rel="noopener">' . esc_html(citami_t('Privacy', 'Privacy')) . '</a></p>';
}