refactor(toc, customizer): improve TOC architecture and reorganize customizer settings

- Reorganized Customizer structure for improved clarity and maintainability
- Introduced consistent default values for all settings to ensure stable fallbacks
  when no user preferences are defined

- Refactored scroll-driven TOC implementation:
  - Optimized scroll handling using requestAnimationFrame
  - Reduced layout thrashing and unnecessary DOM reads
  - Improved heading detection logic (deterministic viewport trigger)
  - Enhanced positioning logic (responsive alignment + sidebar awareness)
  - Improved footer collision handling for more robust layout behavior

- Added optional IntersectionObserver-based TOC implementation:
  - Event-driven alternative to scroll-based approach
  - Currently not enabled by default
  - May not be supported long-term due to less deterministic behavior

- General cleanup and internal consistency improvements

chore: bump version to 2.4.0

inc/customizer/general.php

@@ -10,7 +10,24 @@ add_action( 'customize_register', 'zeitfresser_general_options' );
 function zeitfresser_general_options( $wp_customize ) {
 
     /**
-     * General Section (falls nicht schon vorhanden)
+     * 🔥 Custom Heading Control
+     */
+    if ( class_exists( 'WP_Customize_Control' ) ) {
+        class ZTFR_Customize_Heading_Control extends WP_Customize_Control {
+            public $type = 'ztfr-heading';
+
+            public function render_content() {
+                ?>
+                <span style="display:block; font-weight:600; font-size:14px; margin:15px 0 5px;">
+                    <?php echo esc_html( $this->label ); ?>
+                </span>
+                <?php
+            }
+        }
+    }
+
+    /**
+     * General Section
      */
     if ( ! $wp_customize->get_section( 'ztfr_general' ) ) {
         $wp_customize->add_section(
@@ -23,28 +40,23 @@ function zeitfresser_general_options( $wp_customize ) {
     }
 
     /**
-     * Excerpt Length
+     * ------------------------
+     * HEADER
+     * ------------------------
      */
-    $wp_customize->add_setting(
-        'post_snippet_excerpt_size',
-        array(
-            'default'           => 20,
-            'sanitize_callback' => 'absint',
-        )
-    );
+    $wp_customize->add_setting( 'ztfr_header_heading', array(
+        'sanitize_callback' => 'sanitize_text_field',
+    ));
 
     $wp_customize->add_control(
-        'post_snippet_excerpt_size',
-        array(
-            'type'        => 'number',
-            'section'     => 'ztfr_general',
-            'label'       => 'Excerpt Length (Post Cards)',
-            'description' => 'Number of words shown in post previews.',
-            'input_attrs' => array(
-                'min'  => 5,
-                'max'  => 100,
-                'step' => 1,
-            ),
+        new ZTFR_Customize_Heading_Control(
+            $wp_customize,
+            'ztfr_header_heading',
+            array(
+                'label'    => 'Header',
+                'section'  => 'ztfr_general',
+                'priority' => 1,
+            )
         )
     );
 
@@ -62,9 +74,10 @@ function zeitfresser_general_options( $wp_customize ) {
     $wp_customize->add_control(
         'show_hide_site_title',
         array(
-            'type'    => 'checkbox',
-            'section' => 'ztfr_general',
-            'label'   => 'Show Site Title',
+            'type'     => 'checkbox',
+            'section'  => 'ztfr_general',
+            'label'    => 'Show Site Title',
+            'priority' => 2,
         )
     );
 
@@ -82,9 +95,58 @@ function zeitfresser_general_options( $wp_customize ) {
     $wp_customize->add_control(
         'show_hide_site_tagline',
         array(
-            'type'    => 'checkbox',
-            'section' => 'ztfr_general',
-            'label'   => 'Show Tagline',
+            'type'     => 'checkbox',
+            'section'  => 'ztfr_general',
+            'label'    => 'Show Tagline',
+            'priority' => 3,
+        )
+    );
+
+    /**
+     * ------------------------
+     * GRID
+     * ------------------------
+     */
+    $wp_customize->add_setting( 'ztfr_grid_heading', array(
+        'sanitize_callback' => 'sanitize_text_field',
+    ));
+
+    $wp_customize->add_control(
+        new ZTFR_Customize_Heading_Control(
+            $wp_customize,
+            'ztfr_grid_heading',
+            array(
+                'label'    => 'Grid',
+                'section'  => 'ztfr_general',
+                'priority' => 20,
+            )
+        )
+    );
+
+    /**
+     * Excerpt Length
+     */
+    $wp_customize->add_setting(
+        'post_snippet_excerpt_size',
+        array(
+            'default'           => 25,
+            'sanitize_callback' => 'absint',
+        )
+    );
+
+    $wp_customize->add_control(
+        'post_snippet_excerpt_size',
+        array(
+            'type'        => 'number',
+            'section'     => 'ztfr_general',
+            'label'       => 'Excerpt Length (Post Cards)',
+            'description' => 'Number of words shown in post previews.',
+            'priority'    => 21,
+            'input_attrs' => array(
+                'min'  => 5,
+                'max'  => 100,
+                'step' => 1,
+            ),
         )
     );
 }

inc/customizer/layout.php

@@ -27,7 +27,7 @@ function zeitfresser_layout_options( $wp_customize ) {
             'section'     => 'ztfr_general',
             'label'       => esc_html__( 'Container Width', 'zeitfresser' ),
             'description' => esc_html__( 'Maximum width of the content container in pixels.', 'zeitfresser' ),
-            'priority'    => 10,
+            'priority'    => 22,
             'input_attrs' => array(
                 'min'  => 800,
                 'max'  => 2000,
@@ -47,7 +47,7 @@ function zeitfresser_container_width_dynamic_css() {
     $container_width = (int) get_theme_mod( 'container_width' );
 
     if ( $container_width <= 0 ) {
-        $container_width = 1140;
+        $container_width = 1400;
     }
 
     echo '<style>:root{--container-width:' . esc_attr( $container_width ) . 'px;}</style>';

inc/customizer/social.php

@@ -6,11 +6,6 @@
  */
 
 if ( ! function_exists( 'zeitfresser_get_social_links' ) ) {
-    /**
-     * Return supported social networks.
-     *
-     * @return array<string,string>
-     */
     function zeitfresser_get_social_links() {
         return array(
             'facebook'  => esc_html__( 'Facebook', 'zeitfresser' ),
@@ -31,31 +26,52 @@ add_action( 'customize_register', 'zeitfresser_social_links' );
 
 function zeitfresser_social_links( $wp_customize ) {
 
-    $social_links = zeitfresser_get_social_links();
+    /**
+     * 🔥 Heading Control (falls noch nicht vorhanden)
+     */
+    if ( class_exists( 'WP_Customize_Control' ) && ! class_exists( 'ZTFR_Customize_Heading_Control' ) ) {
+        class ZTFR_Customize_Heading_Control extends WP_Customize_Control {
+            public $type = 'ztfr-heading';
+
+            public function render_content() {
+                ?>
+                <span style="display:block; font-weight:600; font-size:14px; margin:15px 0 5px;">
+                    <?php echo esc_html( $this->label ); ?>
+                </span>
+                <?php
+            }
+        }
+    }
 
     /**
-     * Section Divider
+     * ------------------------
+     * SOCIAL HEADING
+     * ------------------------
      */
     $wp_customize->add_setting(
         'ztfr_social_heading',
         array(
-            'sanitize_callback' => 'wp_kses_post',
+            'sanitize_callback' => 'sanitize_text_field',
         )
     );
 
     $wp_customize->add_control(
-        'ztfr_social_heading',
-        array(
-            'section'     => 'ztfr_general',
-            'type'        => 'hidden',
-            'description' => '<hr><strong>' . esc_html__( 'Social Links', 'zeitfresser' ) . '</strong>',
-            'priority'    => 30,
+        new ZTFR_Customize_Heading_Control(
+            $wp_customize,
+            'ztfr_social_heading',
+            array(
+                'label'    => esc_html__( 'Social Links', 'zeitfresser' ),
+                'section'  => 'ztfr_general',
+                'priority' => 30,
+            )
         )
     );
 
     /**
      * Social URLs
      */
+    $social_links = zeitfresser_get_social_links();
+
     $priority = 31;
 
     foreach ( $social_links as $key => $label ) {

inc/customizer/toc.php

@@ -10,27 +10,48 @@ add_action( 'customize_register', 'zeitfresser_toc_options' );
 function zeitfresser_toc_options( $wp_customize ) {
 
     /**
-     * Section Divider (UI only)
+     * 🔥 Heading Control (falls noch nicht vorhanden)
+     */
+    if ( class_exists( 'WP_Customize_Control' ) && ! class_exists( 'ZTFR_Customize_Heading_Control' ) ) {
+        class ZTFR_Customize_Heading_Control extends WP_Customize_Control {
+            public $type = 'ztfr-heading';
+
+            public function render_content() {
+                ?>
+                <span style="display:block; font-weight:600; font-size:14px; margin:15px 0 5px;">
+                    <?php echo esc_html( $this->label ); ?>
+                </span>
+                <?php
+            }
+        }
+    }
+
+    /**
+     * ------------------------
+     * TOC HEADING
+     * ------------------------
      */
     $wp_customize->add_setting(
         'ztfr_toc_heading',
         array(
-            'sanitize_callback' => 'wp_kses_post',
+            'sanitize_callback' => 'sanitize_text_field',
         )
     );
 
     $wp_customize->add_control(
-        'ztfr_toc_heading',
-        array(
-            'section'     => 'ztfr_general',
-            'type'        => 'hidden',
-            'description' => '<hr><strong>' . esc_html__( 'Article TOC', 'zeitfresser' ) . '</strong>',
-            'priority'    => 20,
+        new ZTFR_Customize_Heading_Control(
+            $wp_customize,
+            'ztfr_toc_heading',
+            array(
+                'label'    => esc_html__( 'TOC', 'zeitfresser' ),
+                'section'  => 'ztfr_general',
+                'priority' => 10,
+            )
         )
     );
 
     /**
-     * Toggle TOC
+     * Show TOC
      */
     $wp_customize->add_setting(
         'show_article_toc',
@@ -47,7 +68,7 @@ function zeitfresser_toc_options( $wp_customize ) {
             'section'     => 'ztfr_general',
             'label'       => esc_html__( 'Show Article TOC', 'zeitfresser' ),
             'description' => esc_html__( 'Enable floating TOC on single posts.', 'zeitfresser' ),
-            'priority'    => 21,
+            'priority'    => 11,
         )
     );
 
@@ -67,9 +88,9 @@ function zeitfresser_toc_options( $wp_customize ) {
         array(
             'type'        => 'number',
             'section'     => 'ztfr_general',
-            'label'       => esc_html__( 'Minimum Headlines for TOC', 'zeitfresser' ),
+            'label'       => esc_html__( 'Minimum Headlines', 'zeitfresser' ),
             'description' => esc_html__( 'TOC appears only if this number of headings is reached.', 'zeitfresser' ),
-            'priority'    => 22,
+            'priority'    => 12,
             'input_attrs' => array(
                 'min'  => 1,
                 'max'  => 50,