<?php

defined( 'ABSPATH' ) || exit;
/**
 * Content-Inventar (F2): scannt alle veröffentlichten Seiten/Beiträge,
 * extrahiert Sections aus dem gerenderten HTML und ordnet Themen zu.
 *
 * WICHTIG: Erkennung und ID-Berechnung müssen exakt dem Frontend-Tracker
 * (assets/js/tracker.js) entsprechen, damit Registry-IDs und Tracking-IDs
 * zusammenpassen. Bei Änderungen IMMER beide Seiten anpassen.
 */
class ADSEC_Inventory {
    /** Kanonisches Themen-Set (abgestimmt 11.06.2026; hero/cta ergänzt 12.06.). */
    const TOPIC_LABELS = array(
        'hero'       => 'Hero/Intro',
        'leistungen' => 'Leistungen',
        'ueber-uns'  => 'Über uns',
        'team'       => 'Team',
        'jobs'       => 'Jobs',
        'news'       => 'News/Blog',
        'referenzen' => 'Referenzen/Projekte',
        'preise'     => 'Preise',
        'faq'        => 'FAQ',
        'kontakt'    => 'Kontakt',
        'standort'   => 'Standort',
        'cta'        => 'Abschluss-CTA',
        'unbekannt'  => '– unbekannt –',
    );

    /**
     * Struktur-Signale: enthaltene Widgets/Elemente verraten das Thema
     * zuverlässiger als Text (Klassifikation v2, 12.06.2026).
     * Muster wird gegen die Widget-Token (elementor-widget-XYZ, wp-block-XYZ)
     * der Section geprüft.
     */
    const WIDGET_SIGNALS = array(
        'kontakt'    => array(
            'form',
            'wpforms',
            'contact',
            'gravityforms'
        ),
        'standort'   => array('google_maps', 'google-maps', 'map'),
        'referenzen' => array(
            'testimonial',
            'reviews',
            'portfolio',
            'logo'
        ),
        'preise'     => array('price-table', 'price-list', 'pricing'),
        'faq'        => array('accordion', 'toggle', 'faq'),
        'team'       => array('team-member', 'team', 'person'),
        'news'       => array('posts', 'loop-grid', 'latest-posts'),
    );

    /** Link-Ziel-Signale: URL-Pfade in der Section verraten das Thema. */
    const HREF_SIGNALS = array(
        'jobs'       => array(
            'job',
            'karriere',
            'career',
            'stelle'
        ),
        'kontakt'    => array('kontakt', 'contact', 'anfrage'),
        'leistungen' => array('leistung', 'service'),
        'referenzen' => array(
            'referenz',
            'projekt',
            'portfolio',
            'kunden'
        ),
        'preise'     => array('preis', 'pricing', 'tarif'),
        'team'       => array('team'),
        'ueber-uns'  => array('ueber', 'about', 'unternehmen'),
        'news'       => array('blog', 'news', 'aktuelles'),
        'standort'   => array('standort', 'anfahrt'),
        'faq'        => array('faq'),
    );

    /** DE/EN-Lexikon: Begriff (lowercase) => Thema. Überschrift zählt doppelt. */
    const LEXICON = array(
        'leistungen' => array(
            'leistung',
            'service',
            'angebot',
            'kompetenz',
            'lösung',
            'solution',
            'was wir tun',
            'was wir bieten'
        ),
        'ueber-uns'  => array(
            'über uns',
            'ueber uns',
            'about',
            'unternehmen',
            'wir sind',
            'geschichte',
            'philosophie',
            'werte',
            'mission'
        ),
        'team'       => array(
            'team',
            'mitarbeiter',
            'ansprechpartner',
            'köpfe',
            'people'
        ),
        'jobs'       => array(
            'job',
            'karriere',
            'career',
            'offene stelle',
            'stellenangebot',
            'bewerbung',
            'bewirb',
            'bewerben',
            'mitarbeiten'
        ),
        'news'       => array(
            'news',
            'blog',
            'aktuell',
            'neuigkeit',
            'presse',
            'magazin'
        ),
        'referenzen' => array(
            'referenz',
            'projekt',
            'portfolio',
            'case',
            'kunden',
            'testimonial',
            'bewertung',
            'erfahrungen'
        ),
        'preise'     => array(
            'preis',
            'pricing',
            'paket',
            'tarif',
            'kosten'
        ),
        'faq'        => array('faq', 'häufige fragen', 'fragen und antworten'),
        'kontakt'    => array(
            'kontakt',
            'contact',
            'anfrage',
            'termin vereinbaren',
            'schreiben sie uns'
        ),
        'standort'   => array(
            'standort',
            'anfahrt',
            'öffnungszeiten',
            'adresse',
            'so finden sie uns',
            'location'
        ),
    );

    /**
     * Themen, die als Einstieg oder Abschluss gelten und deshalb automatisch fest
     * an ihrem Platz bleiben (0.44.4: Kontakt und Jobs dazu — auf w-mm.at sprangen
     * „Bewirb dich" und „Sprechen Sie mit uns" an den Seitenanfang).
     */
    const ANCHOR_TOPICS = array(
        'hero',
        'cta',
        'kontakt',
        'jobs'
    );

    /** Klassen-Token, die eine Section markieren — Spiegel der tracker.js-SELECTORS. */
    const SECTION_CLASSES = array(
        'elementor-section',
        'e-con',
        // Elementor
        'et_pb_section',
        // Divi
        'vc_row',
        // WPBakery
        'ct-section',
        'brxe-section',
        // Oxygen, Bricks
        'fusion-fullwidth',
        // Avada / Fusion Builder
        'fl-row',
        // Beaver Builder
        'brz-section',
        // Brizy
        'panel-grid',
        // SiteOrigin Page Builder
        'wp-block-cover',
        // Gutenberg
        'bde-section',
        // Breakdance (0.51.0)
        'kb-row-layout-wrap',
        // Kadence Blocks (0.51.0)
        'uagb-is-root-container',
        // Spectra (0.51.0)
        'gb-container',
    );

    const SCAN_BATCH = 40;

    const REPORT_OPTION = 'adsec_scan_report';

    // post id => [ builder, sections ] of the last scan
    /**
     * Page builders by their markup, most specific first. Supported = Sectivio
     * recognizes their sections (checked in tests/compat). Names are brand names.
     */
    const BUILDERS = array(
        'elementor'      => array('Elementor', true, '/elementor-element|elementor-section/'),
        'divi'           => array('Divi', true, '/et_pb_section/'),
        'wpbakery'       => array('WPBakery', true, '/wpb-content-wrapper|vc_row/'),
        'avada'          => array('Avada', true, '/fusion-fullwidth/'),
        'beaver'         => array('Beaver Builder', true, '/fl-builder-content/'),
        'bricks'         => array('Bricks', true, '/brxe-/'),
        'breakdance'     => array('Breakdance', true, '/bde-section|bde-f-container/'),
        'oxygen'         => array('Oxygen', true, '/oxy-container|ct-section/'),
        'brizy'          => array('Brizy', true, '/brz-section/'),
        'siteorigin'     => array('SiteOrigin Page Builder', true, '/panel-grid/'),
        'kadence'        => array('Kadence Blocks', true, '/kb-row-layout/'),
        'spectra'        => array('Spectra', true, '/uagb-is-root-container/'),
        'generateblocks' => array('GenerateBlocks', true, '/gb-element-|gb-container/'),
        'thrive'         => array('Thrive Architect', false, '/thrv_wrapper|tve_flt/'),
        'zion'           => array('Zion Builder', false, '/znpb-|zb-section/'),
        'cornerstone'    => array('Cornerstone', false, '/cs-content|x-section/'),
        'visualcomposer' => array('Visual Composer', false, '/vce-row/'),
        'gutenberg'      => array('WordPress blocks', true, '/wp-block-/'),
    );

    /** Which page builder made this page? Slug from BUILDERS, or '' (theme only). */
    public static function detect_builder( $html ) {
        $body = (string) $html;
        $i = stripos( $body, '<body' );
        if ( false !== $i ) {
            $body = substr( $body, $i );
            // ignore stylesheet names in <head>
        }
        foreach ( self::BUILDERS as $slug => $b ) {
            if ( preg_match( $b[2], $body ) ) {
                return $slug;
            }
        }
        return '';
    }

    /**
     * Summary of the last scan for the content overview: builders found (with the
     * number of pages), pages without sections, and unsupported builders.
     */
    public static function scan_summary() {
        $report = (array) get_option( self::REPORT_OPTION, array() );
        $out = array(
            'builders'    => array(),
            'empty'       => array(),
            'unsupported' => array(),
            'sections'    => 0,
        );
        foreach ( $report as $post_id => $r ) {
            list( $b, $n ) = array_pad( (array) $r, 2, 0 );
            $out['sections'] += (int) $n;
            if ( '' !== $b && isset( self::BUILDERS[$b] ) ) {
                $name = ( 'gutenberg' === $b ? __( 'WordPress blocks', 'sectivio' ) : self::BUILDERS[$b][0] );
                $out['builders'][$name] = ($out['builders'][$name] ?? 0) + 1;
                if ( !self::BUILDERS[$b][1] ) {
                    $out['unsupported'][$name] = ($out['unsupported'][$name] ?? 0) + 1;
                }
            }
            if ( 0 === (int) $n && 'page' === get_post_type( (int) $post_id ) ) {
                $out['empty'][] = (int) $post_id;
            }
        }
        arsort( $out['builders'] );
        return $out;
    }

    /** Header/footer areas of builders and themes – mirror of HEADER_RE / FOOTER_RE in tracker.js. */
    const HEADER_MARKERS = '/ (elementor-location-header|fusion-tb-header|bde-header-builder|brz-section__header|fl-theme-builder-header|site-header) /';

    const FOOTER_MARKERS = '/ (elementor-location-footer|fusion-tb-footer|bde-footer|brz-section__footer|fl-theme-builder-footer|site-footer) /';

    /**
     * Content-Quality-Gate (v0.7.0): Mindest-Score, damit eine Section
     * seitenübergreifend eingeblendet (reusable) werden darf. Verhindert, dass
     * inhaltsarme Deko-/Spacer-/Icon-Sections in den Stufe-2-Pool gelangen —
     * der Bandit würde solche erst nach verschwendetem Traffic aussortieren.
     */
    const MIN_REUSABLE_SCORE = 25;

    /**
     * Rechtstext-Begriffe (v0.8.0): Seiten wie Impressum/Datenschutz/AGB werden
     * automatisch von der Optimierung ausgenommen — weder umsortiert noch als
     * Einblende-Quelle genutzt (rechtliches Risiko). Geprüft als ganze Tokens
     * gegen Slug + Titel; der User kann pro Seite übersteuern. Bindestriche in
     * Slug und Begriff werden zu Leerzeichen normalisiert (Wortgrenzen-Match).
     */
    const LEGAL_TERMS = array(
        'impressum',
        'imprint',
        'datenschutz',
        'datenschutzerklaerung',
        'datenschutzerklärung',
        'privacy',
        'privacy policy',
        'agb',
        'allgemeine geschaeftsbedingungen',
        'allgemeine geschäftsbedingungen',
        'nutzungsbedingungen',
        'terms',
        'terms of service',
        'terms and conditions',
        'terms of use',
        'widerruf',
        'widerrufsbelehrung',
        'widerrufsrecht',
        'revocation',
        'cancellation',
        'refund',
        'refund policy',
        'rechtliches',
        'legal',
        'legal notice',
        'disclaimer',
        'haftungsausschluss',
        'cookie',
        'cookies',
        'cookie policy',
        'cookie richtlinie',
        'dsgvo',
        'gdpr'
    );

    /* ---------- Scan ---------- */
    /**
     * Scannt einen Batch veröffentlichter Inhalte. Mehrfach aufrufen, bis
     * 'remaining' 0 ist (Admin-Button). Gibt Fortschritt zurück.
     */
    public static function scan_site( $batch = self::SCAN_BATCH ) {
        $offset = (int) get_option( 'adsec_scan_offset', 0 );
        $query = new WP_Query(array(
            'post_type'      => array('page', 'post'),
            'post_status'    => 'publish',
            'posts_per_page' => max( 1, (int) $batch ),
            'offset'         => $offset,
            'orderby'        => 'ID',
            'order'          => 'ASC',
            'fields'         => 'ids',
        ));
        $scanned = 0;
        $found = 0;
        foreach ( $query->posts as $post_id ) {
            $found += self::scan_post( $post_id );
            $scanned++;
        }
        $total = (int) $query->found_posts;
        $remaining = max( 0, $total - $offset - $scanned );
        update_option( 'adsec_scan_offset', ( $remaining > 0 ? $offset + $scanned : 0 ), false );
        return array(
            'scanned'   => $scanned,
            'sections'  => $found,
            'remaining' => $remaining,
            'done'      => $offset + $scanned,
            'total'     => $total,
        );
    }

    /**
     * Holt das gerenderte HTML einer Seite per Loopback-Request und
     * registriert die erkannten Sections. So funktioniert die Erkennung
     * editor-unabhängig (Elementor/Divi/... rendern erst zur Laufzeit).
     */
    public static function scan_post( $post_id ) {
        $url = get_permalink( $post_id );
        $response = wp_remote_get( $url, array(
            'timeout'   => 15,
            'sslverify' => false,
        ) );
        if ( is_wp_error( $response ) || 200 !== wp_remote_retrieve_response_code( $response ) ) {
            return 0;
        }
        $html = wp_remote_retrieve_body( $response );
        $sections = self::detect_sections( $html );
        // 0.51.0: remember the page builder and the number of sections per page, so
        // the content overview can say what was found (and what is not supported).
        $report = (array) get_option( self::REPORT_OPTION, array() );
        $report[$post_id] = array(self::detect_builder( $html ), count( $sections ));
        update_option( self::REPORT_OPTION, $report, false );
        $seen = array();
        foreach ( $sections as $s ) {
            self::register_section( $post_id, $s );
            $seen[] = $s['uid'];
        }
        if ( !empty( $seen ) ) {
            self::prune_stale_sections( $post_id, $seen );
        }
        return count( $sections );
    }

    /**
     * Entfernt Sections einer Seite, die im aktuellen Render NICHT mehr
     * vorkommen (behebt den Phantom-Drift: heading-basierte UIDs erzeugten
     * bei jeder Render-Variation neue Datensätze). Kuratierte Sections
     * bleiben geschützt: manuell/KI-Thema, gepinnt oder ausgeschlossen.
     */
    private static function prune_stale_sections( $post_id, array $seen_uids ) {
        global $wpdb;
        $table = ADSEC_Database::sections_table();
        $params = array_merge( array($table, $post_id), array_values( $seen_uids ) );
        // Entfernt werden: (a) unbearbeitete Abschnitte, (b) nur AUTOMATISCH fixierte
        // (Einstieg/Abschluss — Thema hero/cta, nicht von Hand geändert) und (c) alles,
        // was seit 30 Tagen nicht mehr auf der Seite vorkam. Von Hand Gepflegtes bleibt
        // so lange erhalten, falls ein Abschnitt nur vorübergehend fehlt.
        $params[] = gmdate( 'Y-m-d H:i:s', time() - 30 * DAY_IN_SECONDS );
        // phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.NoCaching -- custom plugin table.
        $wpdb->query( $wpdb->prepare( "DELETE FROM %i\n\t\t\t WHERE page_id = %d\n\t\t\t   AND uid NOT IN (" . implode( ',', array_fill( 0, count( $seen_uids ), '%s' ) ) . ")\n\t\t\t   AND (\n\t\t\t        ( topic_source = 'auto' AND excluded = 0 AND ( pinned = 0 OR topic IN ('hero','cta','kontakt','jobs') ) )\n\t\t\t     OR last_seen < %s\n\t\t\t   )", $params ) );
    }

    /**
     * Spiegel von detectSections() in tracker.js: Kandidaten sammeln,
     * verschachtelte entfernen, größte Geschwister-Gruppe wählen.
     */
    public static function detect_sections( $html ) {
        if ( !class_exists( 'DOMDocument' ) || '' === trim( $html ) ) {
            return array();
        }
        libxml_use_internal_errors( true );
        $dom = new DOMDocument();
        $dom->loadHTML( '<?xml encoding="utf-8" ?>' . $html );
        libxml_clear_errors();
        $xpath = new DOMXPath($dom);
        $queries = array();
        foreach ( self::SECTION_CLASSES as $cls ) {
            $queries[] = "//*[contains(concat(' ', normalize-space(@class), ' '), ' {$cls} ')]";
        }
        $queries[] = "//main/*[contains(concat(' ', normalize-space(@class), ' '), ' wp-block-group ')]";
        $queries[] = "//*[contains(concat(' ', normalize-space(@class), ' '), ' entry-content ')]/*[contains(concat(' ', normalize-space(@class), ' '), ' wp-block-group ')]";
        $queries[] = "//*[contains(concat(' ', normalize-space(@class), ' '), ' wp-block-post-content ')]/*[contains(concat(' ', normalize-space(@class), ' '), ' wp-block-group ')]";
        $queries[] = "//*[starts-with(@class, 'gb-element-') or contains(@class, ' gb-element-')]";
        // GenerateBlocks 2
        $queries[] = '//main/section';
        $queries[] = '//article/section';
        // 0.48.1: sections hidden on every device (e.g. Elementor "hide on desktop,
        // tablet and mobile") are not part of the page for visitors – never read in.
        $devices = self::hide_devices();
        $candidates = array();
        foreach ( $queries as $q ) {
            foreach ( $xpath->query( $q ) as $el ) {
                if ( self::is_hidden_everywhere( $el, $devices, true ) || '' !== self::region_of( $el ) ) {
                    continue;
                    // hidden for everyone, or part of the site header/footer
                }
                if ( !in_array( $el, $candidates, true ) ) {
                    $candidates[] = $el;
                }
            }
        }
        // Dokument-Reihenfolge herstellen (die Kandidaten stammen aus mehreren Abfragen;
        // Zeilennummern taugen bei minifiziertem HTML nicht).
        $order = array();
        foreach ( $candidates as $i => $el ) {
            $order[$i] = (int) $xpath->evaluate( 'count(preceding::*)', $el );
        }
        asort( $order );
        $candidates = array_values( array_map( function ( $i ) use($candidates) {
            return $candidates[$i];
        }, array_keys( $order ) ) );
        $best = self::best_group( self::top_level( $candidates, null ) );
        // 0.51.0: look inside wrappers. Block themes (Twenty Twenty-Five …) and some
        // builders wrap the whole page in one container that matches the section
        // classes itself; the real sections sit inside it. With one or two top-level
        // candidates, descend into the one that holds (nearly) all of the content.
        for ($level = 0; $level < 4 && count( $best ) <= 2; $level++) {
            $total = 0;
            foreach ( $best as $el ) {
                $total += self::text_len( $el );
            }
            $inner = array();
            foreach ( $best as $el ) {
                if ( 1 === count( $best ) || $total > 0 && self::text_len( $el ) / $total >= 0.7 ) {
                    $inner = self::best_group( self::top_level( $candidates, $el ) );
                    break;
                }
            }
            if ( count( $inner ) < 2 || count( $inner ) <= count( $best ) ) {
                break;
            }
            $best = $inner;
        }
        if ( count( $best ) < 2 ) {
            return array();
        }
        $result = array();
        $total = count( $best );
        foreach ( array_values( $best ) as $index => $el ) {
            $classes = $el->getAttribute( 'class' );
            $uid_head = self::first_heading( $xpath, $el );
            // same as the browser sees in the markup (section id)
            $snapshot = '';
            // Hidden parts inside the section (a hidden button, form or heading) must
            // not decide what the section is about or which enquiries exist.
            self::strip_hidden( $xpath, $el, $devices );
            $heading = self::first_heading( $xpath, $el );
            $text = preg_replace( '/\\s+/u', ' ', trim( $el->textContent ) );
            $item = array(
                'uid'      => self::section_uid(
                    $el->tagName,
                    $classes,
                    $uid_head,
                    $index,
                    self::stable_key( $el )
                ),
                'heading'  => $heading,
                'classes'  => $classes,
                'index'    => $index,
                'total'    => $total,
                'excerpt'  => mb_substr( $text, 0, 180 ),
                'text'     => mb_substr( $text, 0, 1500 ),
                'features' => self::extract_features( $xpath, $el ),
                'region'   => self::region_of( $el ),
            );
            $result[] = $item;
        }
        // 0.49.0: a short lead-in ("We offer the following services:") belongs to the
        // section after it – the two only make sense together.
        $last = count( $result ) - 1;
        foreach ( $result as $i => $item ) {
            $result[$i]['lead_in'] = ( $i < $last && self::is_lead_in( $item ) ? 1 : 0 );
        }
        return $result;
    }

    /**
     * Candidates that are not inside another candidate – within $within (a
     * candidate itself, excluded) or on the whole page. Mirror of topLevel() in tracker.js.
     */
    private static function top_level( array $candidates, $within ) {
        $out = array();
        foreach ( $candidates as $el ) {
            if ( $el === $within ) {
                continue;
            }
            $inside = null === $within;
            $nested = false;
            for ($p = $el->parentNode; $p instanceof DOMNode; $p = $p->parentNode) {
                if ( null !== $within && $p === $within ) {
                    $inside = true;
                    break;
                }
                if ( in_array( $p, $candidates, true ) ) {
                    $nested = true;
                    break;
                }
            }
            if ( $inside && !$nested ) {
                $out[] = $el;
            }
        }
        return $out;
    }

    /**
     * Largest group of siblings (same parent). Key = XPath of the parent:
     * spl_object_hash() is unreliable for DOM nodes. libxml's HTML4 parser sometimes
     * hangs sections directly on <body>; such strays join the previous content group,
     * the way the browser's HTML5 parser sees them. Mirror of bestGroup() in tracker.js.
     */
    private static function best_group( array $els ) {
        $groups = array();
        $last_key = null;
        $last_parent = '';
        foreach ( $els as $el ) {
            $parent = $el->parentNode;
            $is_stray = $parent instanceof DOMElement && in_array( strtolower( $parent->tagName ), array('body', 'html'), true );
            // A content group directly in <main> is parsed correctly; a section outside
            // <main> really is outside (Bricks puts a closing call to action there).
            $merge = $is_stray && null !== $last_key && 'main' !== $last_parent;
            $key = ( $merge ? $last_key : $parent->getNodePath() );
            $groups[$key][] = $el;
            if ( '' === self::region_of( $el ) && !$merge ) {
                $last_key = $key;
                $last_parent = ( $parent instanceof DOMElement ? strtolower( $parent->tagName ) : '' );
            }
        }
        $best = array();
        foreach ( $groups as $group ) {
            if ( count( $group ) > count( $best ) ) {
                $best = $group;
            }
        }
        return $best;
    }

    /** Visible text length (whitespace collapsed) – mirror of textLen() in tracker.js. */
    private static function text_len( DOMElement $el ) {
        return mb_strlen( trim( preg_replace( '/\\s+/u', ' ', $el->textContent ) ) );
    }

    /**
     * Does this section only lead into the next one? A heading with little text and
     * nothing of its own (no picture, form, button, video), or a short text that
     * points ahead ("the following", "our services:", ending with a colon).
     * When in doubt it links: a pair that is never split costs nothing.
     */
    public static function is_lead_in( array $s ) {
        $f = (array) ($s['features'] ?? array());
        if ( !empty( $f['form'] ) || !empty( $f['media'] ) ) {
            return false;
        }
        $heading = trim( (string) ($s['heading'] ?? '') );
        $text = trim( (string) ($s['text'] ?? '') );
        if ( '' !== $heading && 0 === mb_stripos( $text, $heading ) ) {
            $text = trim( mb_substr( $text, mb_strlen( $heading ) ) );
        }
        // Content of its own: a picture, a link or button (also from add-ons), a
        // slider, a map … Layout pieces (columns, groups, inner containers) are not.
        $own = !empty( $f['raster'] ) || !empty( $f['buttons'] ) || !empty( $f['hrefs'] ) || !empty( $f['link_text_len'] );
        foreach ( (array) ($f['widgets'] ?? array()) as $w ) {
            if ( preg_match( '/image|gallery|video|embed|button|form|map|carousel|slider|icon|counter|testimonial|accordion|tabs?\\b|table|audio|file|social|html|shortcode|countdown|rating|progress|price|lottie|media|spotify|youtube/', $w ) ) {
                $own = true;
            }
        }
        $all = $heading . ' ' . $text;
        $cue = (bool) preg_match( '/(nachfolgend|im folgenden|folgende[nrs]?\\b|hier (finden|sehen) sie|das bieten wir|was wir (bieten|anbieten|machen)|unsere leistungen|unser angebot|unsere projekte|unsere referenzen|the following|below you|our services|what we (offer|do))/iu', $all ) || ':' === mb_substr( rtrim( $heading ), -1 ) || ':' === mb_substr( rtrim( $text ), -1 );
        if ( '' !== $heading && !$own && mb_strlen( $text ) < 160 ) {
            return true;
        }
        return $cue && !$own && mb_strlen( $text ) < 400;
    }

    /** Lead-in found by the rules or by the AI (Pro). */
    public static function is_auto_lead( $row ) {
        return 1 === (int) $row->lead_in || 1 === (int) ($row->lead_ai ?? 0);
    }

    /**
     * Devices a section must be hidden on to count as hidden for everyone
     * (0.48.1). Elementor can have extra breakpoints (laptop, widescreen …); a
     * section that is still shown on one of them is visible. Passed to the
     * browser too (ADSEC_CFG.hideDevices), so server and browser agree.
     */
    public static function hide_devices() {
        $devices = array('desktop', 'tablet', 'mobile');
        if ( class_exists( '\\Elementor\\Plugin' ) && isset( \Elementor\Plugin::$instance->breakpoints ) ) {
            try {
                $active = (array) \Elementor\Plugin::$instance->breakpoints->get_active_breakpoints();
                if ( $active ) {
                    $devices = array_merge( array('desktop'), array_keys( $active ) );
                }
            } catch ( \Throwable $e ) {
                $devices = array('desktop', 'tablet', 'mobile');
            }
        }
        return array_values( array_unique( array_map( 'strval', $devices ) ) );
    }

    /**
     * Is this element hidden for every visitor by its own markup? Mirror of
     * hiddenEverywhere() in tracker.js. Covers the "hide on device" switches of
     * Elementor, WPBakery and Avada, the hidden attribute and inline display:none.
     * Other ways of hiding (theme CSS) are checked in the browser.
     */
    public static function hidden_by_markup(
        $classes,
        $style,
        $hidden_attr,
        array $devices
    ) {
        if ( $hidden_attr ) {
            return true;
        }
        if ( false !== strpos( strtolower( preg_replace( '/\\s+/', '', (string) $style ) ), 'display:none' ) ) {
            return true;
        }
        $c = ' ' . preg_replace( '/\\s+/', ' ', (string) $classes ) . ' ';
        $has = function ( array $tokens ) use($c) {
            foreach ( $tokens as $t ) {
                if ( false === strpos( $c, ' ' . $t . ' ' ) ) {
                    return false;
                }
            }
            return true;
        };
        $elementor = array();
        foreach ( $devices as $d ) {
            $elementor[] = 'elementor-hidden-' . $d;
        }
        return $has( $elementor ) || $has( array(
            'vc_hidden-lg',
            'vc_hidden-md',
            'vc_hidden-sm',
            'vc_hidden-xs'
        ) ) || $has( array('fusion-no-small-visibility', 'fusion-no-medium-visibility', 'fusion-no-large-visibility') ) || $has( array('kb-v-lg-hidden', 'kb-v-md-hidden', 'kb-v-sm-hidden') ) || $has( array('uag-hide-desktop', 'uag-hide-tab', 'uag-hide-mob') );
        // Spectra
    }

    /** Hidden for everyone – the element itself or (with $ancestors) one of its parents. */
    private static function is_hidden_everywhere( DOMElement $el, array $devices, $ancestors = false ) {
        for ($n = $el; $n instanceof DOMElement; $n = ( $ancestors ? $n->parentNode : null )) {
            if ( self::hidden_by_markup(
                $n->getAttribute( 'class' ),
                $n->getAttribute( 'style' ),
                $n->hasAttribute( 'hidden' ),
                $devices
            ) ) {
                return true;
            }
        }
        return false;
    }

    /** Removes the parts of a section that no visitor can see (analysis copy only). */
    private static function strip_hidden( DOMXPath $xpath, DOMElement $el, array $devices ) {
        $q = './/*[@hidden or contains(@style, "none") or contains(@class, "elementor-hidden-") or contains(@class, "vc_hidden-") or contains(@class, "fusion-no-") or contains(@class, "kb-v-") or contains(@class, "uag-hide-")]';
        $nodes = array();
        foreach ( $xpath->query( $q, $el ) as $n ) {
            $nodes[] = $n;
        }
        foreach ( $nodes as $n ) {
            if ( $n->parentNode && self::is_hidden_everywhere( $n, $devices ) ) {
                $n->parentNode->removeChild( $n );
            }
        }
    }

    /**
     * Inhalts-Merkmale einer Section: Formulare, Bilder, Button-Texte,
     * Widget-Token, Link-Pfade. Grundlage für Klassifikation v2 und die
     * Inhalts-Badges im Inventar.
     */
    private static function extract_features( DOMXPath $xpath, DOMElement $el ) {
        $features = array(
            'form'    => 0,
            'imgs'    => 0,
            'tel'     => 0,
            'mailto'  => 0,
            'buttons' => array(),
            'widgets' => array(),
            'hrefs'   => array(),
        );
        $features['form'] = $xpath->query( './/form', $el )->length;
        $features['media'] = $xpath->query( './/iframe | .//video', $el )->length;
        $features['imgs'] = $xpath->query( './/img', $el )->length;
        // Bildtypen für das Content-Quality-Gate (v0.7.0): echte Fotos (Raster)
        // zählen stark, SVG-Icons/Logos nur schwach. WICHTIG: Lazy-Load (WP Rocket
        // u. a.) legt die echte URL in data-src/data-lazy-src, nicht in src.
        $raster = 0;
        $svg = 0;
        foreach ( $xpath->query( './/img', $el ) as $img ) {
            $src = $img->getAttribute( 'src' );
            if ( '' === $src || false !== strpos( $src, 'data:image' ) ) {
                $src = $img->getAttribute( 'data-src' );
            }
            if ( '' === $src ) {
                $src = $img->getAttribute( 'data-lazy-src' );
            }
            $src = strtolower( $src );
            if ( preg_match( '/\\.svg(\\?|$)/', $src ) ) {
                $svg++;
            } elseif ( preg_match( '/\\.(jpe?g|png|webp|gif|avif)(\\?|$)/', $src ) ) {
                $raster++;
            } elseif ( '' !== $src ) {
                $raster++;
                // unbekannte Endung -> konservativ als echtes Bild werten
            }
        }
        $features['raster'] = $raster;
        $features['svg'] = $svg;
        // Navigations-/Menü-Marker (v0.7.1): Footer-Menüs, Mega-Menüs und
        // Haupt-Navigation sehen „textreich" aus (viele Menü-Labels), sind aber
        // nie einblendbarer Inhalt. Sitzen meist auf Nachfahren, nicht auf der
        // Section selbst — daher hier per Nachfahren-Query erkennen.
        $nav_query = './/nav' . ' | .//*[contains(concat(" ", normalize-space(@class), " "), " menu-item ")]' . ' | .//*[contains(@class, "jet-mega-menu")]' . ' | .//*[contains(@class, "elementor-nav-menu")]' . ' | .//*[contains(@class, "wp-block-navigation")]';
        $features['nav'] = ( $xpath->query( $nav_query, $el )->length > 0 ? 1 : 0 );
        // Link-Textlänge für die Link-Dichte: Footer/Menü = fast nur Link-Text,
        // echte Inhalts-Sections haben viel Text AUSSERHALB von Links.
        $link_text = '';
        foreach ( $xpath->query( './/a', $el ) as $a ) {
            $link_text .= ' ' . $a->textContent;
        }
        $features['link_text_len'] = mb_strlen( preg_replace( '/\\s+/u', ' ', trim( $link_text ) ) );
        $button_query = './/a[contains(concat(" ", normalize-space(@class), " "), " elementor-button ")]' . ' | .//*[contains(concat(" ", normalize-space(@class), " "), " wp-block-button__link ")]' . ' | .//button';
        foreach ( $xpath->query( $button_query, $el ) as $btn ) {
            $label = preg_replace( '/\\s+/u', ' ', trim( $btn->textContent ) );
            if ( '' !== $label && count( $features['buttons'] ) < 4 ) {
                $features['buttons'][] = mb_substr( $label, 0, 30 );
            }
        }
        foreach ( $xpath->query( './/a[@href]', $el ) as $a ) {
            $href = $a->getAttribute( 'href' );
            // Conversion-Erkennung: Telefon-/E-Mail-Links als mögliche Erfolge markieren
            // (unabhängig vom hrefs-Limit, daher 'continue' statt 'break').
            if ( preg_match( '/^\\s*tel:/i', $href ) ) {
                $features['tel'] = 1;
            } elseif ( preg_match( '/^\\s*mailto:/i', $href ) ) {
                $features['mailto'] = 1;
            }
            if ( count( $features['hrefs'] ) >= 10 ) {
                continue;
            }
            $path = wp_parse_url( $href, PHP_URL_PATH );
            if ( $path && '/' !== $path ) {
                $features['hrefs'][] = $path;
            }
        }
        $widgets = array();
        foreach ( $xpath->query( './/*[contains(@class, "elementor-widget-") or contains(@class, "wp-block-")]', $el ) as $w ) {
            if ( preg_match_all( '/(?:elementor-widget|wp-block)-([a-z0-9_-]{2,30})/', $w->getAttribute( 'class' ), $m ) ) {
                foreach ( $m[1] as $token ) {
                    $widgets[$token] = 1;
                }
            }
            if ( count( $widgets ) > 20 ) {
                break;
            }
        }
        $features['widgets'] = array_keys( $widgets );
        return $features;
    }

    /**
     * Region einer Section anhand ihrer Vorfahren (v0.7.1): Elementor markiert
     * Header/Footer am Eltern-Container (elementor-location-header/-footer), nicht
     * an der Section selbst; zusätzlich <header>/<footer>-Tags. Sections in diesen
     * Regionen sind nie einblendbarer Inhalt.
     *
     * @return string 'header' | 'footer' | '' (= regulärer Inhalt)
     */
    private static function region_of( DOMElement $el ) {
        // 0.51.0: the element itself counts too, plus the header/footer markers of
        // Avada, Breakdance, Brizy, Beaver Themer and classic themes. A <header> or
        // <footer> inside <main> is content (a hero can be built as <header>).
        for ($p = $el; $p instanceof DOMElement; $p = $p->parentNode) {
            $tag = strtolower( $p->tagName );
            if ( 'body' === $tag || 'html' === $tag ) {
                break;
                // Beaver Themer puts its header/footer classes on <body>
            }
            $cls = ' ' . $p->getAttribute( 'class' ) . ' ';
            if ( preg_match( self::FOOTER_MARKERS, $cls ) || 'footer' === $tag && !self::inside_main( $p ) ) {
                return 'footer';
            }
            if ( preg_match( self::HEADER_MARKERS, $cls ) || 'header' === $tag && !self::inside_main( $p ) ) {
                return 'header';
            }
        }
        return '';
    }

    private static function inside_main( DOMElement $el ) {
        for ($p = $el->parentNode; $p instanceof DOMElement; $p = $p->parentNode) {
            if ( 'main' === strtolower( $p->tagName ) ) {
                return true;
            }
        }
        return false;
    }

    private static function first_heading( DOMXPath $xpath, DOMElement $el ) {
        $node = $xpath->query( './/h1 | .//h2 | .//h3', $el )->item( 0 );
        return ( $node ? trim( $node->textContent ) : '' );
    }

    /**
     * Identisch zu sectionId() in tracker.js:
     * FNV-1a(UTF-16-Code-Units) über "TAG|klasse1.klasse2.klasse3|Überschrift(40)".
     */
    public static function section_uid(
        $tag,
        $classes,
        $heading,
        $index,
        $stable = ''
    ) {
        if ( '' !== $stable ) {
            return self::fnv1a_utf16( strtoupper( $tag ) . '|k:' . $stable );
        }
        $class_sig = implode( '.', array_slice( explode( ' ', $classes ), 0, 3 ) );
        $head_sig = ( '' !== $heading ? mb_substr( $heading, 0, 40 ) : 'i' . $index );
        return self::fnv1a_utf16( strtoupper( $tag ) . '|' . $class_sig . '|' . $head_sig );
    }

    /** Feste Builder-Kennung — Spiegel von stableKey() in tracker.js. */
    private static function stable_key( DOMElement $el ) {
        foreach ( array('data-id', 'data-node', 'id') as $attr ) {
            $v = (string) $el->getAttribute( $attr );
            if ( '' !== $v ) {
                return $v;
            }
        }
        return '';
    }

    private static function fnv1a_utf16( $str ) {
        $utf16 = mb_convert_encoding( $str, 'UTF-16LE', 'UTF-8' );
        $hash = 0x811c9dc5;
        $len = strlen( $utf16 );
        for ($i = 0; $i + 1 < $len; $i += 2) {
            $code = ord( $utf16[$i] ) | ord( $utf16[$i + 1] ) << 8;
            $hash ^= $code;
            $hash = $hash * 0x1000193 & 0xffffffff;
        }
        return str_pad(
            dechex( $hash ),
            8,
            '0',
            STR_PAD_LEFT
        );
    }

    /* ---------- Themen-Klassifikation v2 (Multi-Signal, 12.06.2026) ---------- */
    /**
     * Gewichtete Signale statt nur Überschrift:
     *   Überschrift ×4 · Struktur/Widgets +4 · Button-Texte ×3 · Link-Ziele ×3
     *   Fließtext ×1 (gedeckelt) · Seitenkontext ×2 (schwacher Prior)
     * Fallback für signalarme Sections: Position -> Hero/Intro (erste) bzw.
     * Abschluss-CTA (letzte mit Button) — deckt die meisten
     * "(ohne Überschrift)"-Fälle ab.
     */
    public static function classify( array $s, $post_id ) {
        $heading = mb_strtolower( $s['heading'] );
        $text = mb_strtolower( ( isset( $s['text'] ) ? $s['text'] : $s['excerpt'] ) );
        $features = $s['features'];
        $buttons = mb_strtolower( implode( ' ', $features['buttons'] ) );
        $hrefs = mb_strtolower( implode( ' ', $features['hrefs'] ) );
        $widgets = implode( ' ', $features['widgets'] );
        $page_ctx = mb_strtolower( get_post_field( 'post_name', $post_id ) . ' ' . get_the_title( $post_id ) );
        // 0) Kurze Aufrufe mit Button (0.44.4): „Interessiert? Wir sprechen gerne …"
        // wurde als Leistungen erkannt, „Bewirb dich bei uns … coolen Projekten" als
        // Referenzen — beide sprangen dadurch frei über die Seite.
        if ( !empty( $features['buttons'] ) && count( preg_split( '/\\s+/u', trim( $heading . ' ' . $text ) ) ) <= 40 ) {
            $all = $heading . ' ' . $text . ' ' . $buttons;
            if ( preg_match( '/bewirb|bewerb|karriere|wir suchen dich|apply now|join (our|the) team|career/u', $all ) ) {
                return 'jobs';
            }
            if ( preg_match( '/interessiert|sprechen (sie|wir)|melden sie sich|kontaktieren sie|jetzt anfragen|termin vereinbaren|get in touch|let\'s talk|contact us|talk to us/u', $all ) ) {
                return 'cta';
            }
        }
        $scores = array();
        $add = function ( $topic, $points ) use(&$scores) {
            $scores[$topic] = ($scores[$topic] ?? 0) + $points;
        };
        // 1) Struktur-Signale (stärkstes Einzelsignal).
        if ( $features['form'] > 0 ) {
            $add( 'kontakt', 4 );
        }
        foreach ( self::WIDGET_SIGNALS as $topic => $tokens ) {
            foreach ( $tokens as $token ) {
                if ( false !== strpos( $widgets, $token ) ) {
                    $add( $topic, 4 );
                    break;
                }
            }
        }
        // 2) Link-Ziele.
        foreach ( self::HREF_SIGNALS as $topic => $tokens ) {
            foreach ( $tokens as $token ) {
                if ( false !== strpos( $hrefs, $token ) ) {
                    $add( $topic, 3 );
                    break;
                }
            }
        }
        // 3) Lexikon gegen Überschrift, Buttons, Fließtext, Seitenkontext.
        foreach ( self::LEXICON as $topic => $terms ) {
            $text_hits = 0;
            foreach ( $terms as $term ) {
                if ( false !== mb_strpos( $heading, $term ) ) {
                    $add( $topic, 4 );
                }
                if ( '' !== $buttons && false !== mb_strpos( $buttons, $term ) ) {
                    $add( $topic, 3 );
                }
                if ( $text_hits < 2 && false !== mb_strpos( $text, $term ) ) {
                    $add( $topic, 1 );
                    $text_hits++;
                }
                if ( false !== mb_strpos( $page_ctx, $term ) ) {
                    $add( $topic, 2 );
                }
            }
        }
        arsort( $scores );
        $best_topic = key( $scores );
        $best_score = ( $scores ? current( $scores ) : 0 );
        if ( $best_score >= 4 ) {
            return $best_topic;
        }
        // 4) Positions-Fallback für signalarme Sections.
        $index = ( isset( $s['index'] ) ? (int) $s['index'] : 0 );
        $total = ( isset( $s['total'] ) ? (int) $s['total'] : 1 );
        if ( 0 === $index ) {
            return 'hero';
        }
        if ( $index === $total - 1 && !empty( $features['buttons'] ) ) {
            return 'cta';
        }
        return ( $best_score > 0 ? $best_topic : 'unbekannt' );
    }

    /* ---------- Content-Quality-Gate (v0.7.0) ---------- */
    /**
     * Bewertet, wie viel echten Inhalt eine Section trägt (0–100). Editor-
     * agnostisch aus Text, Bildern, Buttons, Formularen, Links. Struktur-
     * Container (Header/Nav/Footer), Spacer/Divider und komplett leere Blöcke
     * bekommen 0 und sind damit nie seitenübergreifend einblendbar.
     *
     * Wird beim Scannen je Section berechnet und gespeichert; entscheidet das
     * a-priori-Gate für den Stufe-2-Pool, BEVOR der Bandit überhaupt lernt.
     *
     * @param array $s Section-Daten (heading, classes, text|excerpt, features).
     */
    public static function compute_content_score( array $s ) {
        $classes = ' ' . mb_strtolower( ( isset( $s['classes'] ) ? $s['classes'] : '' ) ) . ' ';
        // Struktur-Container sind nie Inhalts-Sections -> hartes 0.
        foreach ( array(
            'site-header',
            'site-footer',
            'elementor-location-header',
            'elementor-location-footer',
            ' header ',
            ' footer ',
            'main-navigation'
        ) as $needle ) {
            if ( false !== strpos( $classes, $needle ) ) {
                return 0;
            }
        }
        // Reine Deko (Abstandshalter/Trennlinien) -> 0.
        foreach ( array('spacer', 'divider', 'elementor-element-empty') as $needle ) {
            if ( false !== strpos( $classes, $needle ) ) {
                return 0;
            }
        }
        // Region-Kontext (v0.7.1): Section im Header-/Footer-Template -> kein
        // einblendbarer Inhalt (Elementor markiert die Region am Eltern-Container).
        $region = ( isset( $s['region'] ) ? $s['region'] : '' );
        if ( 'footer' === $region || 'header' === $region ) {
            return 0;
        }
        $heading = ( isset( $s['heading'] ) ? trim( (string) $s['heading'] ) : '' );
        $text = ( isset( $s['text'] ) ? $s['text'] : (( isset( $s['excerpt'] ) ? $s['excerpt'] : '' )) );
        $textlen = mb_strlen( preg_replace( '/\\s+/u', ' ', trim( (string) $text ) ) );
        $f = ( isset( $s['features'] ) && is_array( $s['features'] ) ? $s['features'] : array() );
        $hrefs = ( isset( $f['hrefs'] ) && is_array( $f['hrefs'] ) ? count( $f['hrefs'] ) : 0 );
        $buttons = ( isset( $f['buttons'] ) && is_array( $f['buttons'] ) ? count( $f['buttons'] ) : 0 );
        $form = ( isset( $f['form'] ) ? (int) $f['form'] : 0 );
        $raster = ( isset( $f['raster'] ) ? (int) $f['raster'] : 0 );
        $svg = ( isset( $f['svg'] ) ? (int) $f['svg'] : 0 );
        // Altdaten ohne Typ-Aufschlüsselung (vor v0.7.0): Bilder konservativ
        // als Raster werten, damit der Backfill nichts grundlos sperrt.
        if ( 0 === $raster && 0 === $svg && !empty( $f['imgs'] ) ) {
            $raster = (int) $f['imgs'];
        }
        // Navigation/Menü (v0.7.1): erkanntes Menü-Widget (Mega-Menü, Nav, Footer-
        // Menü) -> nie Inhalt, egal wie textreich die Menü-Labels wirken.
        if ( !empty( $f['nav'] ) ) {
            return 0;
        }
        // Link-Dichte: steckt fast der gesamte Text in Links -> Footer/Menü.
        // (Echte CTA-Section: Überschrift+Fließtext außerhalb, nur Button verlinkt.)
        $link_text_len = ( isset( $f['link_text_len'] ) ? (int) $f['link_text_len'] : 0 );
        if ( $textlen > 40 && $link_text_len / $textlen > 0.6 ) {
            return 0;
        }
        // Fallback: viele Links, kaum Text -> Menü, kein Inhalt.
        if ( $hrefs >= 8 && $textlen < 100 ) {
            return 0;
        }
        // Komplett leer (kein Text, kein echtes Bild, kein Formular) -> 0.
        if ( $textlen < 8 && 0 === $raster && 0 === $form ) {
            return 0;
        }
        $score = 0;
        $score += min( (int) floor( $textlen / 12 ), 30 );
        // Fließtext bis 30
        $score += ( '' !== $heading && mb_strlen( $heading ) > 3 ? 8 : 0 );
        $score += min( $raster * 10, 30 );
        // echte Bilder bis 30
        $score += min( $svg * 2, 6 );
        // Icons/Logos schwach
        $score += ( $form ? 20 : 0 );
        // Lead-Capture stark
        $score += min( $buttons * 6, 12 );
        // CTAs
        $score += min( $hrefs, 6 );
        // Links
        return (int) min( $score, 100 );
    }

    /**
     * Backfill nach dem Upgrade auf v0.7.0: bewertet bereits erfasste Sections
     * aus den gespeicherten Feldern (excerpt/features/classes) neu. Liefert
     * provisorische Scores; ein voller Re-Scan verfeinert sie (volltext statt
     * 200-Zeichen-Excerpt). Nur Zeilen ohne Score (=0) werden angefasst.
     */
    public static function backfill_scores() {
        global $wpdb;
        $table = ADSEC_Database::sections_table();
        // phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.NoCaching -- custom plugin table.
        $rows = $wpdb->get_results( $wpdb->prepare( 'SELECT id, heading, classes, excerpt, features FROM %i WHERE content_score = 0', $table ) );
        foreach ( $rows as $r ) {
            $score = self::compute_content_score( array(
                'heading'  => $r->heading,
                'classes'  => $r->classes,
                'excerpt'  => $r->excerpt,
                'features' => ( json_decode( (string) $r->features, true ) ?: array() ),
            ) );
            if ( $score > 0 ) {
                // phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.NoCaching -- custom plugin table.
                $wpdb->update( $table, array(
                    'content_score' => $score,
                ), array(
                    'id' => (int) $r->id,
                ) );
            }
        }
    }

    /* ---------- Seiten-Sperre: Rechtstexte (v0.8.0) ---------- */
    /**
     * Erkennt automatisch Rechtstext-/Pflichtseiten (Impressum, Datenschutz, AGB,
     * Widerruf …) anhand Slug + Titel sowie der WordPress-Datenschutzseite. Solche
     * Seiten dürfen nicht umsortiert und nicht als Einblende-Quelle genutzt werden.
     */
    public static function is_legal_page( $page_id ) {
        $page_id = (int) $page_id;
        if ( $page_id <= 0 ) {
            return false;
        }
        if ( $page_id === (int) get_option( 'wp_page_for_privacy_policy' ) ) {
            return true;
        }
        $slug = (string) get_post_field( 'post_name', $page_id );
        $title = (string) get_the_title( $page_id );
        // Bindestriche -> Leerzeichen, damit Slug-Tokens als Wörter matchen.
        $hay = ' ' . mb_strtolower( str_replace( '-', ' ', $slug ) . ' ' . $title ) . ' ';
        foreach ( self::LEGAL_TERMS as $term ) {
            if ( preg_match( '/\\b' . preg_quote( $term, '/' ) . '\\b/u', $hay ) ) {
                return true;
            }
        }
        return false;
    }

    /**
     * Effektive Seiten-Sperre: manuelle Übersteuerung schlägt die Auto-Erkennung.
     * 'exclude' = gesperrt, 'include' = freigegeben, sonst Auto-Erkennung.
     */
    public static function is_page_excluded( $page_id ) {
        $page_id = (int) $page_id;
        $overrides = get_option( 'adsec_page_overrides', array() );
        if ( isset( $overrides[$page_id] ) ) {
            return 'exclude' === $overrides[$page_id];
        }
        return self::is_legal_page( $page_id );
    }

    /** Distinct-Themen einer Seite (für Themen-Treue der Einblendungen, Stufe 2). */
    public static function get_page_topics( $page_id ) {
        global $wpdb;
        $table = ADSEC_Database::sections_table();
        // phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.NoCaching -- custom plugin table.
        return $wpdb->get_col( $wpdb->prepare( 'SELECT DISTINCT topic FROM %i WHERE page_id = %d AND excluded = 0', $table, (int) $page_id ) );
    }

    /**
     * Automatisch erkannte mögliche Conversions auf der Website — aus den beim
     * Einlesen erfassten Abschnitts-Merkmalen abgeleitet: Formulare, Telefon-Links
     * (tel:) und E-Mail-Links (mailto:). Grundlage für die Mehrfachauswahl „Was zählt
     * als Erfolg?" — der Admin hakt nur an, was es real gibt. Gibt eine Teilmenge von
     * ['form','tel','mailto'] zurück (leer, solange nichts/Passendes eingelesen wurde).
     */
    public static function detected_goals() {
        global $wpdb;
        $table = ADSEC_Database::sections_table();
        // phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.NoCaching -- custom plugin table.
        $rows = $wpdb->get_col( $wpdb->prepare( 'SELECT features FROM %i', $table ) );
        $has = array(
            'form'   => false,
            'tel'    => false,
            'mailto' => false,
        );
        foreach ( $rows as $json ) {
            $f = json_decode( (string) $json, true );
            if ( !is_array( $f ) ) {
                continue;
            }
            if ( !empty( $f['form'] ) ) {
                $has['form'] = true;
            }
            if ( !empty( $f['tel'] ) ) {
                $has['tel'] = true;
            }
            if ( !empty( $f['mailto'] ) ) {
                $has['mailto'] = true;
            }
        }
        return array_keys( array_filter( $has ) );
    }

    /**
     * Speichert die manuellen Seiten-Einstellungen aus der Inventar-UI: Sperre
     * (Rechtstext-Übersteuerung). Stimmt die Sperr-Wahl mit der Auto-Erkennung
     * überein, wird der Override entfernt.
     *
     * @param array $pages [ page_id => [ 'present' => 1, 'exclude' => '1'? ] ]
     */
    public static function save_page_overrides( array $pages ) {
        $overrides = get_option( 'adsec_page_overrides', array() );
        foreach ( $pages as $page_id => $row ) {
            $page_id = (int) $page_id;
            if ( empty( $row['present'] ) ) {
                continue;
            }
            $desired = !empty( $row['exclude'] );
            $auto = self::is_legal_page( $page_id );
            if ( $desired === $auto ) {
                unset($overrides[$page_id]);
            } else {
                $overrides[$page_id] = ( $desired ? 'exclude' : 'include' );
            }
        }
        update_option( 'adsec_page_overrides', $overrides, false );
    }

    /* ---------- Registry ---------- */
    /**
     * Upsert: neue Section anlegen, bekannte aktualisieren. Manuell gesetzte
     * Themen (topic_source = manual) werden NIE automatisch überschrieben.
     */
    public static function register_section( $post_id, array $s ) {
        global $wpdb;
        $table = ADSEC_Database::sections_table();
        $now = current_time( 'mysql', true );
        // phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.NoCaching -- custom plugin table.
        $existing = $wpdb->get_row( $wpdb->prepare(
            'SELECT id, topic, topic_source, reusable, heading, excerpt FROM %i WHERE page_id = %d AND uid = %s',
            $table,
            $post_id,
            $s['uid']
        ) );
        $common = array(
            'position'      => ( isset( $s['index'] ) ? (int) $s['index'] : 0 ),
            'heading'       => mb_substr( $s['heading'], 0, 160 ),
            'classes'       => mb_substr( $s['classes'], 0, 160 ),
            'excerpt'       => mb_substr( ( isset( $s['excerpt'] ) ? $s['excerpt'] : '' ), 0, 200 ),
            'features'      => wp_json_encode( ( isset( $s['features'] ) ? $s['features'] : array() ) ),
            'content_score' => self::compute_content_score( $s ),
            'lead_in'       => ( empty( $s['lead_in'] ) ? 0 : 1 ),
            'last_seen'     => $now,
        );
        if ( $existing ) {
            // Changed text: the AI's lead-in answer is checked again (0.49.0).
            if ( $existing->heading !== $common['heading'] || $existing->excerpt !== $common['excerpt'] ) {
                $common['lead_ai'] = 2;
            }
            // Re-Scan klassifiziert NUR regelbasiert erkannte Themen neu.
            // Manuell gesetzte ('manual') und KI-Themen ('ai') sind unantastbar.
            if ( 'auto' === $existing->topic_source ) {
                $common['topic'] = self::classify( $s, $post_id );
            }
            // phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.NoCaching -- custom plugin table.
            $wpdb->update( $table, $common, array(
                'id' => $existing->id,
            ) );
            return;
        }
        $topic = self::classify( $s, $post_id );
        $row = array(
            'uid'          => $s['uid'],
            'page_id'      => $post_id,
            'topic'        => $topic,
            'topic_source' => 'auto',
            'excluded'     => 0,
            'first_seen'   => $now,
        );
        // phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.NoCaching -- custom plugin table.
        $wpdb->insert( $table, array_merge( $common, $row ) );
    }

    /** Komplettes Inventar, gruppiert nach Seite (für die Admin-UI). */
    public static function get_inventory() {
        global $wpdb;
        $table = ADSEC_Database::sections_table();
        // Nach visueller Position sortieren (nicht nach Einfüge-id) -> Inventar-
        // Reihenfolge == Website-Reihenfolge, stabil über alle Re-Scans.
        // phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.NoCaching -- custom plugin table.
        $rows = $wpdb->get_results( $wpdb->prepare( 'SELECT * FROM %i ORDER BY page_id ASC, position ASC, id ASC', $table ) );
        $grouped = array();
        foreach ( $rows as $row ) {
            $grouped[(int) $row->page_id][] = $row;
        }
        return $grouped;
    }

    /**
     * Dropdown-Optionen: kanonisches Set + alle vom Admin angelegten
     * Freitext-Themen (Entscheidung 11.06.: eigene Themen möglich).
     */
    /** Themen mit übersetzbarer Bezeichnung (Schlüssel wie TOPIC_LABELS). */
    public static function topic_labels() {
        return array(
            'hero'       => __( 'Hero/intro', 'sectivio' ),
            'leistungen' => __( 'Services', 'sectivio' ),
            'ueber-uns'  => __( 'About us', 'sectivio' ),
            'team'       => __( 'Team', 'sectivio' ),
            'jobs'       => __( 'Jobs', 'sectivio' ),
            'news'       => __( 'News/blog', 'sectivio' ),
            'referenzen' => __( 'References/projects', 'sectivio' ),
            'preise'     => __( 'Pricing', 'sectivio' ),
            'faq'        => __( 'FAQ', 'sectivio' ),
            'kontakt'    => __( 'Contact', 'sectivio' ),
            'standort'   => __( 'Location', 'sectivio' ),
            'cta'        => __( 'Closing call to action', 'sectivio' ),
            'unbekannt'  => __( '– unknown –', 'sectivio' ),
        );
    }

    public static function get_topic_options() {
        global $wpdb;
        $table = ADSEC_Database::sections_table();
        $options = self::topic_labels();
        // phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.NoCaching -- custom plugin table.
        $custom = $wpdb->get_col( $wpdb->prepare( 'SELECT DISTINCT topic FROM %i', $table ) );
        foreach ( $custom as $topic ) {
            if ( !isset( $options[$topic] ) ) {
                $options[$topic] = $topic . ' ' . __( '(custom topic)', 'sectivio' );
            }
        }
        return $options;
    }

    /** Admin-Eingaben aus der Inventar-UI speichern. */
    public static function save_inventory( array $input ) {
        global $wpdb;
        $table = ADSEC_Database::sections_table();
        foreach ( $input as $id => $row ) {
            $id = (int) $id;
            $topic = sanitize_title( $row['topic_custom'] ?? '' );
            $manual = '' !== $topic;
            if ( !$manual ) {
                $topic = sanitize_title( $row['topic'] ?? 'unbekannt' );
                $manual = isset( $row['topic_changed'] ) && '1' === $row['topic_changed'];
            }
            $update = array(
                'topic' => ( $topic ?: 'unbekannt' ),
            );
            // Quelle nur bei aktiver Änderung hochstufen — sonst würde ein
            // bloßes Speichern KI-Themen ('ai') auf 'auto' zurückstufen und
            // der nächste Re-Scan würde sie überschreiben.
            if ( $manual ) {
                $update['topic_source'] = 'manual';
            }
            // phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.NoCaching -- custom plugin table.
            $wpdb->update( $table, $update, array(
                'id' => $id,
            ) );
        }
    }

}