Changeset 3763326

Timestamp:

10/24/2026 01:29:26 PM (9 hours ago)

Author:

seojuice

Message:

Release 2.9.0: save approved headings, roll back all

Location:

seojuice

Files:

• tags/2.9.0 (copied) (copied from seojuice/trunk )
• tags/2.9.0/includes/footprint.php (modified) (7 diffs)
• tags/2.9.0/readme.txt (modified) (3 diffs)
• tags/2.9.0/seojuice.php (modified) (13 diffs)
• trunk/includes/footprint.php (modified) (7 diffs)
• trunk/readme.txt (modified) (3 diffs)
• trunk/seojuice.php (modified) (13 diffs)

seojuice/tags/2.9.0/includes/footprint.php

@@ -212 +212 @@
 }
 
-function seojuice_record_field_version(int $post_id, int $cs_id, string $field, $before_value, $wrote_value = null): void {
+function seojuice_record_field_version(int $post_id, int $cs_id, string $field, $before_value, $wrote_value = null, array $meta_before = array(), array $meta_wrote = array()): void {
     $h = seojuice_get_history($post_id);
     $entry = array(
-        'cs' => $cs_id, 'ts' => time(), 'before' => array(),
+        'cs' => $cs_id, 'ts' => time(), 'before' => $meta_before,
         'before_fields' => array($field => array('value' => $before_value)),
     );
     if ($wrote_value !== null) { $entry['wrote_fields'] = array($field => $wrote_value); }
+    if (!empty($meta_wrote)) { $entry['wrote'] = $meta_wrote; }
     $h[] = $entry;
     seojuice_update_post_meta($post_id, '_seojuice_history', wp_json_encode($h));
@@ -247 +248 @@
 }
 
+// Title variables an SEO plugin template can hold; a pin replaces them with the old post_title.
+function seojuice_title_template_vars(): array {
+    return array('%%title%%', '%title%', '%%post_title%%');
+}
+
+// A history entry written by a heading change: it records post_title in before_fields.
+function seojuice_history_is_heading(array $e): bool {
+    return ($e['type'] ?? '') !== 'content_diff'
+        && isset($e['before_fields']['post_title']) && is_array($e['before_fields']['post_title']);
+}
+
+// A search-title rollback hands its key to the heading entries that passed it through
+// (spec 2.4). Those entries recorded the title key with before equal to this entry's wrote.
+// Leaving the key as it is, or restoring a value that is empty or built from post_title,
+// would let the heading show in the search title. So the key gets the pin the heading
+// needs (the restored template with the old post_title), and the heading entries take it
+// over: the first one restores the title's before, so rolling it back removes the pin.
+// Returns false when no heading entry follows, so the plain splice rules apply.
+function seojuice_revert_title_into_headings(int $post_id, array &$h, int $i, string $key, array $rec, string $s_wrote, array &$key_out): bool {
+    $chain = array();
+    $expected = $s_wrote;
+    $cs_id = (int) ($h[$i]['cs'] ?? 0);
+    $follow = null;
+    for ($j = $i + 1, $n = count($h); $j < $n; $j++) {
+        $e = $h[$j];
+        if ((int) ($e['cs'] ?? 0) === $cs_id || !isset($e['before'][$key])) { continue; }
+        $b = $e['before'][$key];
+        $passes = seojuice_history_is_heading($e) && !empty($b['present'])
+            && (string) ($b['value'] ?? '') === $expected
+            && isset($e['wrote']) && is_array($e['wrote']) && array_key_exists($key, $e['wrote']);
+        if (!$passes) { $follow = $j; break; }
+        $chain[] = $j;
+        $expected = (string) $e['wrote'][$key];
+    }
+    if (!$chain) { return false; }
+
+    if ($follow === null && (string) get_post_meta($post_id, $key, true) !== $expected) {
+        $key_out[$key] = 'kept_edit';
+        return true;
+    }
+    $rec_val = (string) ($rec['value'] ?? '');
+    $final = array('present' => !empty($rec['present']), 'value' => $rec_val);
+    $tpl = $rec_val;
+    if ($tpl === '' && function_exists('seojuice_default_title_template')) {
+        $post = get_post($post_id);
+        $tpl = seojuice_default_title_template($key, $post ? (string) ($post->post_type ?? 'post') : 'post');
+    }
+    $has_var = false;
+    foreach (seojuice_title_template_vars() as $v) { if (strpos($tpl, $v) !== false) { $has_var = true; break; } }
+    if ($has_var) {
+        $old = (string) ($h[$chain[0]]['before_fields']['post_title']['value'] ?? '');
+        $final = array('present' => true, 'value' => str_replace(seojuice_title_template_vars(), $old, $tpl));
+    }
+    foreach ($chain as $n => $j) {
+        $h[$j]['before'][$key] = $n === 0 ? $rec : $final;
+        $h[$j]['wrote'][$key] = $final['value'];
+    }
+    if ($follow !== null) {
+        $fb = $h[$follow]['before'][$key];
+        if (!empty($fb['present']) && (string) ($fb['value'] ?? '') === $expected) { $h[$follow]['before'][$key] = $final; }
+        return true;
+    }
+    if ($final['present']) { seojuice_update_post_meta($post_id, $key, $final['value']); $key_out[$key] = 'restored'; }
+    else { delete_post_meta($post_id, $key); $key_out[$key] = 'absent_restored'; }
+    return true;
+}
+
+// Without an SEO plugin a heading is held by the pin key. When no search title is live
+// after a rollback and a heading entry never wrote its pin (it was applied while a
+// search title overrode the title), write the pin now: the pre-heading post_title.
+function seojuice_guard_core_pin(int $post_id, array &$h): void {
+    $pin = '_seojuice_h1_pin';
+    if ((string) get_post_meta($post_id, '_seojuice_seo_title', true) !== ''
+        || (string) get_post_meta($post_id, $pin, true) !== '') { return; }
+    $open = array();
+    foreach ($h as $j => $e) {
+        if (seojuice_history_is_heading($e) && isset($e['wrote'][$pin]) && (string) $e['wrote'][$pin] === '') { $open[] = $j; }
+    }
+    if (!$open) { return; }
+    $old = (string) ($h[$open[0]]['before_fields']['post_title']['value'] ?? '');
+    if ($old === '') { return; }
+    seojuice_update_post_meta($post_id, $pin, $old);
+    foreach ($open as $n => $j) {
+        $h[$j]['wrote'][$pin] = $old;
+        if ($n > 0) { $h[$j]['before'][$pin] = array('present' => true, 'value' => $old); }
+    }
+}
+
+// Returns skipped (keys and fields left because the client changed them), content_diff,
+// outcome, and key_outcomes: key or field => restored | kept_edit | absent_restored.
+// A key handed to a later live change has no outcome: it stays as that change left it.
 function seojuice_revert_changeset(int $post_id, int $cs_id): array {
     $h = seojuice_get_history($post_id);
     $drop = array();
     $skipped = array();
+    $key_out = array();
+    $own_title_touched = false;
     $content_diff_handled = false;
     $outcome = null;
@@ -270 +364 @@
                 if (!$res['reverted'] && !empty($res['skipped'])) { $skipped[] = 'content'; }
                 if (isset($res['outcome'])) { $outcome = $res['outcome']; }
+                $co = (string) ($res['outcome'] ?? '');
+                if (in_array($co, array('drift_kept', 'marker_stripped'), true)) { $key_out['content'] = 'kept_edit'; }
+                elseif (!empty($res['reverted'])) { $key_out['content'] = 'restored'; }
             }
         }
@@ -277 +374 @@
         $wrote = (isset($entry['wrote']) && is_array($entry['wrote'])) ? $entry['wrote'] : null;
         foreach (($entry['before'] ?? array()) as $key => $rec) {
+            if ($key === '_seojuice_seo_title') { $own_title_touched = true; }
+            // A search title followed by heading entries that passed its key through.
+            if ($wrote !== null && array_key_exists($key, $wrote) && !seojuice_history_is_heading($entry)
+                && seojuice_revert_title_into_headings($post_id, $h, $i, (string) $key, $rec, (string) $wrote[$key], $key_out)) {
+                continue;
+            }
             // Only an entry that proves what it wrote may chain: when the next
             // entry's before is that write, hand it this before value. When a client
@@ -293 +396 @@
                 && (string) get_post_meta($post_id, $key, true) !== (string) $wrote[$key]) {
                 $skipped[] = $key;
+                $key_out[$key] = 'kept_edit';
                 continue;
             }
-            if (!empty($rec['present'])) { seojuice_update_post_meta($post_id, $key, $rec['value']); }
-            else { delete_post_meta($post_id, $key); }
+            if (!empty($rec['present'])) { seojuice_update_post_meta($post_id, $key, $rec['value']); $key_out[$key] = 'restored'; }
+            else { delete_post_meta($post_id, $key); $key_out[$key] = 'absent_restored'; }
         }
         $wf = (isset($entry['wrote_fields']) && is_array($entry['wrote_fields'])) ? $entry['wrote_fields'] : null;
@@ -311 +415 @@
                 $post = get_post($post_id);
                 $cur = ($post && $field === 'post_title') ? (string) $post->post_title : '';
-                if ($cur !== (string) $wf[$field]) { $skipped[] = $field; continue; }
+                if ($cur !== (string) $wf[$field]) { $skipped[] = $field; $key_out[$field] = 'kept_edit'; continue; }
             }
             seojuice_update_post(array('ID' => $post_id, $field => $rec['value']));
+            $key_out[$field] = 'restored';
         }
     }
@@ -320 +425 @@
         if (!isset($drop[$i])) { $kept[] = $entry; }
     }
+    if ($own_title_touched) { seojuice_guard_core_pin($post_id, $kept); }
     seojuice_update_post_meta($post_id, '_seojuice_history', wp_json_encode($kept));
     if (!$blocked) { seojuice_drop_persisted($post_id, $cs_id); }
-    return array('skipped' => $skipped, 'content_diff' => $content_diff_handled, 'outcome' => $outcome);
+    return array('skipped' => $skipped, 'content_diff' => $content_diff_handled, 'outcome' => $outcome, 'key_outcomes' => $key_out);
 }
 

seojuice/tags/2.9.0/readme.txt

@@ -2 +2 @@
 Contributors: seojuice
 Tags: seo, internal links, ai search, meta tags, visibility tracking
-Stable tag: 2.8.1
+Stable tag: 2.9.0
 Requires at least: 6.2
 Tested up to: 7.1
@@ -138 +138 @@
 
 == Changelog ==
+
+= 2.9.0 =
+* New: approved page headings can be saved in WordPress, with their own confirmation. Your search title stays as it is.
+* New: Roll back all on a page puts it back as it was before SEOJuice.
+* Improved: rollback tells you when it kept an edit you made yourself.
 
 = 2.8.1 =
@@ -320 +325 @@
 == Upgrade Notice ==
 
+= 2.9.0 =
+Approved page headings can now be saved in WordPress, and Roll back all puts a page back as it was before SEOJuice.
+
 = 2.8.1 =
 Rollback fix: rolling back SEOJuice changes in any order now restores the right value and keeps your own edits.

seojuice/tags/2.9.0/seojuice.php

@@ -4 +4 @@
 Description: SEOJuice automated on-page SEO optimization with server-side rendering for better performance and crawlability.
 Author: Vadim Kravcenko
-Version: 2.8.1
+Version: 2.9.0
 Author URI: https://seojuice.io
 License: GPLv2
@@ -44 +44 @@
 //   is_ssl() actually cached under. Adds GET /front-page (page_on_front lookup)
 //   so meta_update changes targeting the homepage can resolve a post id.
-const SEOJUICE_PLUGIN_VERSION = '2.8.1';
+const SEOJUICE_PLUGIN_VERSION = '2.9.0';
 // API base defaults to production. Overridable (before the plugin loads, e.g.
 // via wp-config.php or an mu-plugin) or through the SEOJUICE_API_BASE env var,
@@ -2045 +2045 @@
 
 function seojuice_read_seo_title($post_id) {
+    if (seojuice_pin_capable() === 'core') {
+        return (string) get_post_meta($post_id, SEOJUICE_OWN_TITLE_KEY, true);
+    }
     foreach (seojuice_active_seo_title_keys() as $k) {
         $v = (string) get_post_meta($post_id, $k, true);
@@ -2052 +2055 @@
 }
 
+const SEOJUICE_OWN_TITLE_KEY = '_seojuice_seo_title';
+const SEOJUICE_PIN_KEY       = '_seojuice_h1_pin';
+const SEOJUICE_TITLE_PRIORITY = 15;
+
+// True when a title/SEO plugin we cannot write for controls the document title.
+function seojuice_unsupported_title_owner_active() {
+    return defined('AIOSEO_VERSION') || class_exists('AIOSEO\\Plugin\\AIOSEO')
+        || function_exists('the_seo_framework') || defined('THE_SEO_FRAMEWORK_VERSION')
+        || defined('SLIM_SEO_VER');
+}
+
+// True when a callback that is not ours sits on $tag at a priority above $min_prio
+// (null = any priority).
+// WordPress core formats document_title with these (default-filters.php); they never replace it.
+const SEOJUICE_CORE_TITLE_FORMATTERS = array('wptexturize', 'convert_chars', 'esc_html', 'capital_P_dangit');
+
+function seojuice_foreign_title_callback($tag, $min_prio = null) {
+    global $wp_filter;
+    if (empty($wp_filter[$tag])) { return false; }
+    $h = $wp_filter[$tag];
+    $cbs = is_object($h) && isset($h->callbacks) ? $h->callbacks : (is_array($h) ? $h : array());
+    foreach ($cbs as $prio => $fns) {
+        if ($min_prio !== null && (int) $prio <= $min_prio) { continue; }
+        foreach ((array) $fns as $fn) {
+            $f = is_array($fn) && isset($fn['function']) ? $fn['function'] : $fn;
+            if (is_string($f) && (strpos($f, 'seojuice_') === 0 || in_array($f, SEOJUICE_CORE_TITLE_FORMATTERS, true))) { continue; }
+            return true;
+        }
+    }
+    return false;
+}
+
+// A foreign pre_get_document_title or document_title callback at any priority, or a
+// document_title_parts callback after ours, can replace what we render.
+function seojuice_foreign_title_conflict() {
+    return seojuice_foreign_title_callback('pre_get_document_title')
+        || seojuice_foreign_title_callback('document_title')
+        || seojuice_foreign_title_callback('document_title_parts', SEOJUICE_TITLE_PRIORITY);
+}
+
+// Front-end verdict: $wp_filter during a REST apply can miss filters added only on
+// front-end hooks, so a rendered singular request records what it saw. It runs at
+// wp_head priority 0 so it also sees title filters added on template_redirect or wp_head.
+function seojuice_record_title_render_conflict() {
+    if (!empty($GLOBALS['seojuice_title_conflict_checked']) || is_admin() || is_feed() || !is_singular()) { return; }
+    $GLOBALS['seojuice_title_conflict_checked'] = true;
+    $conflict = seojuice_foreign_title_conflict();
+    $cur = get_option('seojuice_title_render_conflict', null);
+    if (is_array($cur) && !empty($cur['conflict']) === $conflict) { return; }
+    update_option('seojuice_title_render_conflict', array('conflict' => $conflict, 'at' => time()), false);
+}
+add_action('wp_head', 'seojuice_record_title_render_conflict', 0);
+
+// 'seo_plugin' | 'core' | 'unsupported'. Spec 2.2a pin-proven gate.
+function seojuice_pin_capable() {
+    if (seojuice_unsupported_title_owner_active()) { return 'unsupported'; }
+    if (seojuice_active_seo_title_keys()) { return 'seo_plugin'; }
+    if (!function_exists('current_theme_supports') || !current_theme_supports('title-tag')) { return 'unsupported'; }
+    if (seojuice_foreign_title_conflict()) { return 'unsupported'; }
+    $rc = get_option('seojuice_title_render_conflict', null);
+    if (is_array($rc) && !empty($rc['conflict'])) { return 'unsupported'; }
+    return 'core';
+}
+
+function seojuice_pin_key() {
+    $keys = seojuice_active_seo_title_keys();
+    return $keys ? $keys[0] : SEOJUICE_PIN_KEY;
+}
+
+// Returns the post meta string for $key on a singular front-end view of its post, or ''.
+function seojuice_title_meta_for_view($key) {
+    if (is_admin() || is_feed() || !is_singular()) { return ''; }
+    $id = (int) get_queried_object_id();
+    if ($id <= 0) { return ''; }
+    return (string) get_post_meta($id, $key, true);
+}
+
+function seojuice_filter_pre_document_title($title) {
+    $v = seojuice_title_meta_for_view(SEOJUICE_OWN_TITLE_KEY);
+    if ($v === '' || seojuice_pin_capable() !== 'core') { return $title; }
+    return $v;
+}
+add_filter('pre_get_document_title', 'seojuice_filter_pre_document_title', SEOJUICE_TITLE_PRIORITY);
+
+function seojuice_filter_document_title_parts($parts) {
+    // Core builds a static front page title from site name and tagline, not post_title.
+    if (is_front_page()) { return $parts; }
+    if (seojuice_title_meta_for_view(SEOJUICE_OWN_TITLE_KEY) !== '') { return $parts; }
+    $pin = seojuice_title_meta_for_view(SEOJUICE_PIN_KEY);
+    if ($pin === '' || seojuice_pin_capable() !== 'core') { return $parts; }
+    if (!is_array($parts)) { $parts = array(); }
+    $parts['title'] = $pin;
+    return $parts;
+}
+add_filter('document_title_parts', 'seojuice_filter_document_title_parts', SEOJUICE_TITLE_PRIORITY);
+
 function seojuice_capabilities() {
-    $caps = array('persistent_apply', 'footer_backlink', 'url_replace', 'cache_clear', 'apply_reasons', 'content_save_guard', 'seo_title');
+    $caps = array('persistent_apply', 'footer_backlink', 'url_replace', 'cache_clear', 'apply_reasons', 'content_save_guard', 'seo_title', 'headline');
     if (SEOJUICE_CAP_ALT_INLINE) {
         $caps[] = 'alt_inline';
@@ -2521 +2620 @@
             'title' => $post->post_title,
             'seo_title' => seojuice_read_seo_title($post_id),
+            'h1_raw' => seojuice_read_h1_raw($post),
             'status' => $post->post_status,
             'url' => get_permalink($post->ID),
@@ -3590 +3690 @@
 }
 
+// ---------------------------------------------------------------------------
+// headline: change the page heading (H1) without moving the search title.
+// ---------------------------------------------------------------------------
+
+// Comparison form of a heading: tags stripped, entities decoded, typographic
+// quotes/dashes folded to ASCII, whitespace collapsed.
+function seojuice_headline_norm($s): string {
+    $s = html_entity_decode(strip_tags((string) $s), ENT_QUOTES | ENT_HTML5, 'UTF-8');
+    $s = strtr($s, array(
+        "\u{2018}" => "'", "\u{2019}" => "'", "\u{201B}" => "'", "\u{2032}" => "'",
+        "\u{201C}" => '"', "\u{201D}" => '"', "\u{201E}" => '"', "\u{2033}" => '"',
+        "\u{2013}" => '-', "\u{2014}" => '-', "\u{2026}" => '...', "\u{00A0}" => ' ',
+    ));
+    return trim((string) preg_replace('/\s+/u', ' ', $s));
+}
+
+// Parses a body into a wrapper element; null on failure.
+function seojuice_headline_parse(string $content): ?array {
+    $dom = new DOMDocument();
+    $prev = libxml_use_internal_errors(true);
+    $dom->loadHTML('<?xml encoding="UTF-8" ?><div id="seojuice-root">' . $content . '</div>',
+        LIBXML_HTML_NOIMPLIED | LIBXML_HTML_NODEFDTD);
+    libxml_clear_errors(); libxml_use_internal_errors($prev);
+    $root = $dom->getElementById('seojuice-root');
+    return $root ? array($dom, $root) : null;
+}
+
+function seojuice_elementor_has_h1($nodes, array $wanted): bool {
+    if (!is_array($nodes)) { return false; }
+    foreach ($nodes as $n) {
+        if (!is_array($n)) { continue; }
+        if (($n['widgetType'] ?? '') === 'heading'
+            && strtolower((string) ($n['settings']['header_size'] ?? '')) === 'h1'
+            && isset($wanted[seojuice_headline_norm($n['settings']['title'] ?? '')])) {
+            return true;
+        }
+        if (!empty($n['elements']) && seojuice_elementor_has_h1($n['elements'], $wanted)) { return true; }
+    }
+    return false;
+}
+
+// True when a page builder owns the visible H1: writing post_title there would rename
+// menus and leave the heading unchanged.
+function seojuice_headline_in_builder(int $post_id, string $content, array $wanted): bool {
+    if (get_post_meta($post_id, '_fl_builder_enabled', true)) { return true; }
+    $el = get_post_meta($post_id, '_elementor_data', true);
+    if (is_string($el) && $el !== '') { $el = json_decode($el, true); }
+    if (seojuice_elementor_has_h1($el, $wanted)) { return true; }
+    if (strpos($content, '[vc_custom_heading') !== false
+        && preg_match_all('/\[vc_custom_heading\b([^\]]*)\]/', $content, $sc)) {
+        foreach ($sc[1] as $attrs) {
+            if (!preg_match_all('/(\w+)\s*=\s*"([^"]*)"/', $attrs, $kv, PREG_SET_ORDER)) { continue; }
+            $a = array();
+            foreach ($kv as $pair) { $a[$pair[1]] = $pair[2]; }
+            $fc = urldecode($a['font_container'] ?? '');
+            if (preg_match('/(^|\|)tag:h1(\||$)/i', $fc) && isset($wanted[seojuice_headline_norm(urldecode($a['text'] ?? ''))])) {
+                return true;
+            }
+        }
+    }
+    return false;
+}
+
+// Content <h1> elements whose text matches $wanted: array('count' => n, 'text' => raw text
+// of the single match, 'targetable' => the diff engine would edit that very element).
+function seojuice_headline_content_h1(string $content, array $wanted): array {
+    $out = array('count' => 0, 'text' => '', 'targetable' => false);
+    $parsed = seojuice_headline_parse($content);
+    if (!$parsed) { return $out; }
+    list($dom, $root) = $parsed;
+    $match = null;
+    foreach ($dom->getElementsByTagName('h1') as $h) {
+        if (isset($wanted[seojuice_headline_norm($h->textContent)])) { $out['count']++; $match = $h; }
+    }
+    if ($out['count'] !== 1) { return $out; }
+    $out['text'] = $match->textContent;
+    $t = seojuice_locate_diff_target($dom, $root, 'h1', $out['text']);
+    for ($n = $t; $n instanceof DOMNode; $n = $n->parentNode) {
+        if ($n->isSameNode($match)) { $out['targetable'] = true; break; }
+    }
+    return $out;
+}
+
+// Raw text the page shows as its H1: the single content <h1>, else raw post_title.
+// Never get_the_title(), which wptexturize alters.
+function seojuice_read_h1_raw($post): string {
+    $parsed = seojuice_headline_parse((string) $post->post_content);
+    if ($parsed) {
+        $h1s = $parsed[0]->getElementsByTagName('h1');
+        if ($h1s->length === 1) { return trim((string) $h1s->item(0)->textContent); }
+    }
+    return (string) $post->post_title;
+}
+
+function seojuice_default_title_template(string $key, string $post_type): string {
+    $pt = $post_type !== '' ? $post_type : 'post';
+    if ($key === '_yoast_wpseo_title') {
+        $o = get_option('wpseo_titles', array());
+        $t = is_array($o) && isset($o['title-' . $pt]) ? (string) $o['title-' . $pt] : '';
+        return $t !== '' ? $t : '%%title%% %%page%% %%sep%% %%sitename%%';
+    }
+    if ($key === 'rank_math_title') {
+        $o = get_option('rank_math_titles', array());
+        $t = is_array($o) && isset($o['pt_' . $pt . '_title']) ? (string) $o['pt_' . $pt . '_title'] : '';
+        return $t !== '' ? $t : '%title% %sep% %sitename%';
+    }
+    $o = get_option('seopress_titles_option_name', array());
+    $t = is_array($o) && isset($o['seopress_titles_single_titles'][$pt]['title'])
+        ? (string) $o['seopress_titles_single_titles'][$pt]['title'] : '';
+    return $t !== '' ? $t : '%%post_title%% - %%sitetitle%%';
+}
+
+// Pin values to hold the search title steady across a post_title write: key => value
+// to store. A value equal to the live one means no pin is needed (or one already holds).
+function seojuice_headline_pin_values(int $post_id, string $mode, string $old_title, string $post_type): array {
+    $vars = array('%%title%%', '%title%', '%%post_title%%');
+    $out = array();
+    if ($mode === 'core') {
+        $cur = (string) get_post_meta($post_id, SEOJUICE_PIN_KEY, true);
+        $own = (string) get_post_meta($post_id, SEOJUICE_OWN_TITLE_KEY, true);
+        // An earlier pin already holds the pre-heading title; an approved search title
+        // overrides the whole <title>, so the pin is not needed while it is live.
+        $out[SEOJUICE_PIN_KEY] = ($cur !== '' || $own !== '') ? $cur : $old_title;
+        return $out;
+    }
+    foreach (seojuice_active_seo_title_keys() as $key) {
+        $cur = (string) get_post_meta($post_id, $key, true);
+        $tpl = $cur !== '' ? $cur : seojuice_default_title_template($key, $post_type);
+        $has = false;
+        foreach ($vars as $v) { if (strpos($tpl, $v) !== false) { $has = true; break; } }
+        $out[$key] = $has ? str_replace($vars, $old_title, $tpl) : $cur;
+    }
+    return $out;
+}
+
+// Applies one `headline` change. Returns array('result', 'reason', 'target', 'content',
+// 'content_dirty'). Resolution order: page builder, single content <h1>, raw post_title.
+function seojuice_apply_headline(int $post_id, string $content, int $cs_id, array $payload, bool $save_unsafe): array {
+    $res = array('result' => 'skipped', 'reason' => '', 'target' => '', 'content' => $content, 'content_dirty' => false);
+    $new = isset($payload['h1']) && is_string($payload['h1']) ? sanitize_text_field($payload['h1']) : '';
+    $wanted = array();
+    foreach (array('expected_h1', 'crawled_h1') as $k) {
+        $n = isset($payload[$k]) && is_string($payload[$k]) ? seojuice_headline_norm($payload[$k]) : '';
+        if ($n !== '') { $wanted[$n] = true; }
+    }
+    if ($new === '' || !$wanted) { $res['reason'] = 'invalid_payload'; return $res; }
+    if (seojuice_headline_in_builder($post_id, $content, $wanted)) { $res['reason'] = 'h1_in_page_builder'; return $res; }
+
+    $h1 = seojuice_headline_content_h1($content, $wanted);
+    if ($h1['count'] === 1) {
+        if (!$h1['targetable']) { $res['reason'] = 'unlocatable'; return $res; }
+        if ($save_unsafe) { $res['reason'] = 'content_unsafe_to_save'; return $res; }
+        $d = seojuice_apply_content_diff($content, $cs_id, array(
+            'location_dom' => 'h1', 'original_text' => $h1['text'], 'operation' => 'replace',
+            'text' => htmlspecialchars($new, ENT_QUOTES | ENT_SUBSTITUTE, 'UTF-8'),
+        ));
+        if (!$d['applied']) { $res['reason'] = 'unlocatable'; return $res; }
+        seojuice_record_content_diff_version($post_id, $cs_id, $d['before']);
+        return array('result' => 'applied', 'reason' => '', 'target' => 'content_h1',
+            'content' => $d['content'], 'content_dirty' => true);
+    }
+    $post = get_post($post_id);
+    if ($h1['count'] > 1 || !$post || !isset($wanted[seojuice_headline_norm($post->post_title)])) {
+        $res['reason'] = 'h1_not_found';
+        return $res;
+    }
+
+    // A static posts page builds its <title> from single_post_title(), so no pin renders.
+    $mode = seojuice_pin_capable();
+    if ((int) get_option('page_for_posts', 0) === $post_id || $mode === 'unsupported') {
+        $res['reason'] = 'title_would_change';
+        return $res;
+    }
+    // wp_update_post re-saves the stored body through the save filters, so a body kses would strip must not be touched.
+    if ($save_unsafe) { $res['reason'] = 'content_unsafe_to_save'; return $res; }
+    $old_title = (string) $post->post_title;
+    $pins = seojuice_headline_pin_values($post_id, $mode, $old_title, (string) ($post->post_type ?? 'post'));
+    $before = array(); $wrote = array();
+    foreach ($pins as $key => $value) {
+        $present = metadata_exists('post', $post_id, $key);
+        $cur = (string) get_post_meta($post_id, $key, true);
+        $before[$key] = array('present' => $present, 'value' => $cur);
+        if ($value !== $cur) { seojuice_update_post_meta($post_id, $key, $value); }
+        $wrote[$key] = $value;
+    }
+    $updated = seojuice_update_post(array('ID' => $post_id, 'post_title' => $new), true);
+    if (is_wp_error($updated) || !$updated) {
+        foreach ($before as $key => $b) {
+            if ($b['present']) { seojuice_update_post_meta($post_id, $key, $b['value']); }
+            else { delete_post_meta($post_id, $key); }
+        }
+        $res['reason'] = 'update_failed';
+        return $res;
+    }
+    $after = get_post($post_id);
+    $wrote_title = $after ? (string) $after->post_title : $new;
+    seojuice_record_field_version($post_id, $cs_id, 'post_title', $old_title, $wrote_title, $before, $wrote);
+    $res['result'] = 'applied';
+    $res['target'] = 'post_title';
+    return $res;
+}
+
 function seojuice_rest_apply_changes($request) {
     $post_id = intval($request->get_param('id'));
@@ -3613 +3915 @@
     $results      = array();
     $reasons      = array();
+    $targets      = array();
     $persisted_ids = array();
     $alt_commits   = array();
@@ -3705 +4008 @@
         } elseif ($type === 'seo_title') {
             $new = isset($payload['title']) ? sanitize_text_field($payload['title']) : '';
-            $keys = seojuice_active_seo_title_keys();
+            $mode = seojuice_pin_capable();
+            $keys = $mode === 'core' ? array(SEOJUICE_OWN_TITLE_KEY) : seojuice_active_seo_title_keys();
             if ($new === '') {
                 $results[(string) $cs_id] = 'skipped';
@@ -3724 +4028 @@
                 $persisted_ids[] = $cs_id;
             }
+        } elseif ($type === 'headline') {
+            if ($save_unsafe === null) {
+                $save_unsafe = seojuice_save_would_strip_content((string) $owned->post_content);
+            }
+            $res = seojuice_apply_headline($post_id, $content, $cs_id, $payload, $save_unsafe);
+            $results[(string) $cs_id] = $res['result'];
+            if ($res['result'] === 'applied') {
+                $content       = $res['content'];
+                $content_dirty = $content_dirty || $res['content_dirty'];
+                $targets[(string) $cs_id] = $res['target'];
+                $persisted_ids[] = $cs_id;
+            } else {
+                $reasons[(string) $cs_id] = $res['reason'];
+            }
         } elseif ($type === 'og') {
             $map = array(
@@ -3831 +4149 @@
     }
 
-    return new WP_REST_Response(array('success' => true, 'results' => $results, 'reasons' => $reasons), 200);
+    return new WP_REST_Response(array('success' => true, 'results' => $results, 'reasons' => $reasons, 'targets' => $targets), 200);
 }
 
@@ -3848 +4166 @@
     $reverted = array();
     $outcomes = array();
+    $key_outcomes = array();
 
     foreach ($ids as $cs_id) {
@@ -3902 +4221 @@
             $outcome = $res['outcome'] ?? 'absent';
         }
+        // Per-key results for title, heading and meta changes; their change-level
+        // outcome was always 'absent' before, which hid a kept client edit.
+        $ko = (isset($res['key_outcomes']) && is_array($res['key_outcomes'])) ? $res['key_outcomes'] : array();
+        if ($ko) {
+            $key_outcomes[(string) $cs_id] = $ko;
+            if ($outcome === null || $outcome === 'absent') {
+                $outcome = in_array('kept_edit', $ko, true) ? 'drift_kept' : 'restored';
+            }
+        }
         if ($blocked) {
             $outcome = 'blocked';
@@ -3916 +4244 @@
     }
 
-    return new WP_REST_Response(array('success' => true, 'reverted' => $reverted, 'outcomes' => $outcomes), 200);
+    return new WP_REST_Response(array('success' => true, 'reverted' => $reverted, 'outcomes' => $outcomes, 'key_outcomes' => $key_outcomes), 200);
 }
 

seojuice/trunk/includes/footprint.php

@@ -212 +212 @@
 }
 
-function seojuice_record_field_version(int $post_id, int $cs_id, string $field, $before_value, $wrote_value = null): void {
+function seojuice_record_field_version(int $post_id, int $cs_id, string $field, $before_value, $wrote_value = null, array $meta_before = array(), array $meta_wrote = array()): void {
     $h = seojuice_get_history($post_id);
     $entry = array(
-        'cs' => $cs_id, 'ts' => time(), 'before' => array(),
+        'cs' => $cs_id, 'ts' => time(), 'before' => $meta_before,
         'before_fields' => array($field => array('value' => $before_value)),
     );
     if ($wrote_value !== null) { $entry['wrote_fields'] = array($field => $wrote_value); }
+    if (!empty($meta_wrote)) { $entry['wrote'] = $meta_wrote; }
     $h[] = $entry;
     seojuice_update_post_meta($post_id, '_seojuice_history', wp_json_encode($h));
@@ -247 +248 @@
 }
 
+// Title variables an SEO plugin template can hold; a pin replaces them with the old post_title.
+function seojuice_title_template_vars(): array {
+    return array('%%title%%', '%title%', '%%post_title%%');
+}
+
+// A history entry written by a heading change: it records post_title in before_fields.
+function seojuice_history_is_heading(array $e): bool {
+    return ($e['type'] ?? '') !== 'content_diff'
+        && isset($e['before_fields']['post_title']) && is_array($e['before_fields']['post_title']);
+}
+
+// A search-title rollback hands its key to the heading entries that passed it through
+// (spec 2.4). Those entries recorded the title key with before equal to this entry's wrote.
+// Leaving the key as it is, or restoring a value that is empty or built from post_title,
+// would let the heading show in the search title. So the key gets the pin the heading
+// needs (the restored template with the old post_title), and the heading entries take it
+// over: the first one restores the title's before, so rolling it back removes the pin.
+// Returns false when no heading entry follows, so the plain splice rules apply.
+function seojuice_revert_title_into_headings(int $post_id, array &$h, int $i, string $key, array $rec, string $s_wrote, array &$key_out): bool {
+    $chain = array();
+    $expected = $s_wrote;
+    $cs_id = (int) ($h[$i]['cs'] ?? 0);
+    $follow = null;
+    for ($j = $i + 1, $n = count($h); $j < $n; $j++) {
+        $e = $h[$j];
+        if ((int) ($e['cs'] ?? 0) === $cs_id || !isset($e['before'][$key])) { continue; }
+        $b = $e['before'][$key];
+        $passes = seojuice_history_is_heading($e) && !empty($b['present'])
+            && (string) ($b['value'] ?? '') === $expected
+            && isset($e['wrote']) && is_array($e['wrote']) && array_key_exists($key, $e['wrote']);
+        if (!$passes) { $follow = $j; break; }
+        $chain[] = $j;
+        $expected = (string) $e['wrote'][$key];
+    }
+    if (!$chain) { return false; }
+
+    if ($follow === null && (string) get_post_meta($post_id, $key, true) !== $expected) {
+        $key_out[$key] = 'kept_edit';
+        return true;
+    }
+    $rec_val = (string) ($rec['value'] ?? '');
+    $final = array('present' => !empty($rec['present']), 'value' => $rec_val);
+    $tpl = $rec_val;
+    if ($tpl === '' && function_exists('seojuice_default_title_template')) {
+        $post = get_post($post_id);
+        $tpl = seojuice_default_title_template($key, $post ? (string) ($post->post_type ?? 'post') : 'post');
+    }
+    $has_var = false;
+    foreach (seojuice_title_template_vars() as $v) { if (strpos($tpl, $v) !== false) { $has_var = true; break; } }
+    if ($has_var) {
+        $old = (string) ($h[$chain[0]]['before_fields']['post_title']['value'] ?? '');
+        $final = array('present' => true, 'value' => str_replace(seojuice_title_template_vars(), $old, $tpl));
+    }
+    foreach ($chain as $n => $j) {
+        $h[$j]['before'][$key] = $n === 0 ? $rec : $final;
+        $h[$j]['wrote'][$key] = $final['value'];
+    }
+    if ($follow !== null) {
+        $fb = $h[$follow]['before'][$key];
+        if (!empty($fb['present']) && (string) ($fb['value'] ?? '') === $expected) { $h[$follow]['before'][$key] = $final; }
+        return true;
+    }
+    if ($final['present']) { seojuice_update_post_meta($post_id, $key, $final['value']); $key_out[$key] = 'restored'; }
+    else { delete_post_meta($post_id, $key); $key_out[$key] = 'absent_restored'; }
+    return true;
+}
+
+// Without an SEO plugin a heading is held by the pin key. When no search title is live
+// after a rollback and a heading entry never wrote its pin (it was applied while a
+// search title overrode the title), write the pin now: the pre-heading post_title.
+function seojuice_guard_core_pin(int $post_id, array &$h): void {
+    $pin = '_seojuice_h1_pin';
+    if ((string) get_post_meta($post_id, '_seojuice_seo_title', true) !== ''
+        || (string) get_post_meta($post_id, $pin, true) !== '') { return; }
+    $open = array();
+    foreach ($h as $j => $e) {
+        if (seojuice_history_is_heading($e) && isset($e['wrote'][$pin]) && (string) $e['wrote'][$pin] === '') { $open[] = $j; }
+    }
+    if (!$open) { return; }
+    $old = (string) ($h[$open[0]]['before_fields']['post_title']['value'] ?? '');
+    if ($old === '') { return; }
+    seojuice_update_post_meta($post_id, $pin, $old);
+    foreach ($open as $n => $j) {
+        $h[$j]['wrote'][$pin] = $old;
+        if ($n > 0) { $h[$j]['before'][$pin] = array('present' => true, 'value' => $old); }
+    }
+}
+
+// Returns skipped (keys and fields left because the client changed them), content_diff,
+// outcome, and key_outcomes: key or field => restored | kept_edit | absent_restored.
+// A key handed to a later live change has no outcome: it stays as that change left it.
 function seojuice_revert_changeset(int $post_id, int $cs_id): array {
     $h = seojuice_get_history($post_id);
     $drop = array();
     $skipped = array();
+    $key_out = array();
+    $own_title_touched = false;
     $content_diff_handled = false;
     $outcome = null;
@@ -270 +364 @@
                 if (!$res['reverted'] && !empty($res['skipped'])) { $skipped[] = 'content'; }
                 if (isset($res['outcome'])) { $outcome = $res['outcome']; }
+                $co = (string) ($res['outcome'] ?? '');
+                if (in_array($co, array('drift_kept', 'marker_stripped'), true)) { $key_out['content'] = 'kept_edit'; }
+                elseif (!empty($res['reverted'])) { $key_out['content'] = 'restored'; }
             }
         }
@@ -277 +374 @@
         $wrote = (isset($entry['wrote']) && is_array($entry['wrote'])) ? $entry['wrote'] : null;
         foreach (($entry['before'] ?? array()) as $key => $rec) {
+            if ($key === '_seojuice_seo_title') { $own_title_touched = true; }
+            // A search title followed by heading entries that passed its key through.
+            if ($wrote !== null && array_key_exists($key, $wrote) && !seojuice_history_is_heading($entry)
+                && seojuice_revert_title_into_headings($post_id, $h, $i, (string) $key, $rec, (string) $wrote[$key], $key_out)) {
+                continue;
+            }
             // Only an entry that proves what it wrote may chain: when the next
             // entry's before is that write, hand it this before value. When a client
@@ -293 +396 @@
                 && (string) get_post_meta($post_id, $key, true) !== (string) $wrote[$key]) {
                 $skipped[] = $key;
+                $key_out[$key] = 'kept_edit';
                 continue;
             }
-            if (!empty($rec['present'])) { seojuice_update_post_meta($post_id, $key, $rec['value']); }
-            else { delete_post_meta($post_id, $key); }
+            if (!empty($rec['present'])) { seojuice_update_post_meta($post_id, $key, $rec['value']); $key_out[$key] = 'restored'; }
+            else { delete_post_meta($post_id, $key); $key_out[$key] = 'absent_restored'; }
         }
         $wf = (isset($entry['wrote_fields']) && is_array($entry['wrote_fields'])) ? $entry['wrote_fields'] : null;
@@ -311 +415 @@
                 $post = get_post($post_id);
                 $cur = ($post && $field === 'post_title') ? (string) $post->post_title : '';
-                if ($cur !== (string) $wf[$field]) { $skipped[] = $field; continue; }
+                if ($cur !== (string) $wf[$field]) { $skipped[] = $field; $key_out[$field] = 'kept_edit'; continue; }
             }
             seojuice_update_post(array('ID' => $post_id, $field => $rec['value']));
+            $key_out[$field] = 'restored';
         }
     }
@@ -320 +425 @@
         if (!isset($drop[$i])) { $kept[] = $entry; }
     }
+    if ($own_title_touched) { seojuice_guard_core_pin($post_id, $kept); }
     seojuice_update_post_meta($post_id, '_seojuice_history', wp_json_encode($kept));
     if (!$blocked) { seojuice_drop_persisted($post_id, $cs_id); }
-    return array('skipped' => $skipped, 'content_diff' => $content_diff_handled, 'outcome' => $outcome);
+    return array('skipped' => $skipped, 'content_diff' => $content_diff_handled, 'outcome' => $outcome, 'key_outcomes' => $key_out);
 }
 

seojuice/trunk/readme.txt

@@ -2 +2 @@
 Contributors: seojuice
 Tags: seo, internal links, ai search, meta tags, visibility tracking
-Stable tag: 2.8.1
+Stable tag: 2.9.0
 Requires at least: 6.2
 Tested up to: 7.1
@@ -138 +138 @@
 
 == Changelog ==
+
+= 2.9.0 =
+* New: approved page headings can be saved in WordPress, with their own confirmation. Your search title stays as it is.
+* New: Roll back all on a page puts it back as it was before SEOJuice.
+* Improved: rollback tells you when it kept an edit you made yourself.
 
 = 2.8.1 =
@@ -320 +325 @@
 == Upgrade Notice ==
 
+= 2.9.0 =
+Approved page headings can now be saved in WordPress, and Roll back all puts a page back as it was before SEOJuice.
+
 = 2.8.1 =
 Rollback fix: rolling back SEOJuice changes in any order now restores the right value and keeps your own edits.

seojuice/trunk/seojuice.php

@@ -4 +4 @@
 Description: SEOJuice automated on-page SEO optimization with server-side rendering for better performance and crawlability.
 Author: Vadim Kravcenko
-Version: 2.8.1
+Version: 2.9.0
 Author URI: https://seojuice.io
 License: GPLv2
@@ -44 +44 @@
 //   is_ssl() actually cached under. Adds GET /front-page (page_on_front lookup)
 //   so meta_update changes targeting the homepage can resolve a post id.
-const SEOJUICE_PLUGIN_VERSION = '2.8.1';
+const SEOJUICE_PLUGIN_VERSION = '2.9.0';
 // API base defaults to production. Overridable (before the plugin loads, e.g.
 // via wp-config.php or an mu-plugin) or through the SEOJUICE_API_BASE env var,
@@ -2045 +2045 @@
 
 function seojuice_read_seo_title($post_id) {
+    if (seojuice_pin_capable() === 'core') {
+        return (string) get_post_meta($post_id, SEOJUICE_OWN_TITLE_KEY, true);
+    }
     foreach (seojuice_active_seo_title_keys() as $k) {
         $v = (string) get_post_meta($post_id, $k, true);
@@ -2052 +2055 @@
 }
 
+const SEOJUICE_OWN_TITLE_KEY = '_seojuice_seo_title';
+const SEOJUICE_PIN_KEY       = '_seojuice_h1_pin';
+const SEOJUICE_TITLE_PRIORITY = 15;
+
+// True when a title/SEO plugin we cannot write for controls the document title.
+function seojuice_unsupported_title_owner_active() {
+    return defined('AIOSEO_VERSION') || class_exists('AIOSEO\\Plugin\\AIOSEO')
+        || function_exists('the_seo_framework') || defined('THE_SEO_FRAMEWORK_VERSION')
+        || defined('SLIM_SEO_VER');
+}
+
+// True when a callback that is not ours sits on $tag at a priority above $min_prio
+// (null = any priority).
+// WordPress core formats document_title with these (default-filters.php); they never replace it.
+const SEOJUICE_CORE_TITLE_FORMATTERS = array('wptexturize', 'convert_chars', 'esc_html', 'capital_P_dangit');
+
+function seojuice_foreign_title_callback($tag, $min_prio = null) {
+    global $wp_filter;
+    if (empty($wp_filter[$tag])) { return false; }
+    $h = $wp_filter[$tag];
+    $cbs = is_object($h) && isset($h->callbacks) ? $h->callbacks : (is_array($h) ? $h : array());
+    foreach ($cbs as $prio => $fns) {
+        if ($min_prio !== null && (int) $prio <= $min_prio) { continue; }
+        foreach ((array) $fns as $fn) {
+            $f = is_array($fn) && isset($fn['function']) ? $fn['function'] : $fn;
+            if (is_string($f) && (strpos($f, 'seojuice_') === 0 || in_array($f, SEOJUICE_CORE_TITLE_FORMATTERS, true))) { continue; }
+            return true;
+        }
+    }
+    return false;
+}
+
+// A foreign pre_get_document_title or document_title callback at any priority, or a
+// document_title_parts callback after ours, can replace what we render.
+function seojuice_foreign_title_conflict() {
+    return seojuice_foreign_title_callback('pre_get_document_title')
+        || seojuice_foreign_title_callback('document_title')
+        || seojuice_foreign_title_callback('document_title_parts', SEOJUICE_TITLE_PRIORITY);
+}
+
+// Front-end verdict: $wp_filter during a REST apply can miss filters added only on
+// front-end hooks, so a rendered singular request records what it saw. It runs at
+// wp_head priority 0 so it also sees title filters added on template_redirect or wp_head.
+function seojuice_record_title_render_conflict() {
+    if (!empty($GLOBALS['seojuice_title_conflict_checked']) || is_admin() || is_feed() || !is_singular()) { return; }
+    $GLOBALS['seojuice_title_conflict_checked'] = true;
+    $conflict = seojuice_foreign_title_conflict();
+    $cur = get_option('seojuice_title_render_conflict', null);
+    if (is_array($cur) && !empty($cur['conflict']) === $conflict) { return; }
+    update_option('seojuice_title_render_conflict', array('conflict' => $conflict, 'at' => time()), false);
+}
+add_action('wp_head', 'seojuice_record_title_render_conflict', 0);
+
+// 'seo_plugin' | 'core' | 'unsupported'. Spec 2.2a pin-proven gate.
+function seojuice_pin_capable() {
+    if (seojuice_unsupported_title_owner_active()) { return 'unsupported'; }
+    if (seojuice_active_seo_title_keys()) { return 'seo_plugin'; }
+    if (!function_exists('current_theme_supports') || !current_theme_supports('title-tag')) { return 'unsupported'; }
+    if (seojuice_foreign_title_conflict()) { return 'unsupported'; }
+    $rc = get_option('seojuice_title_render_conflict', null);
+    if (is_array($rc) && !empty($rc['conflict'])) { return 'unsupported'; }
+    return 'core';
+}
+
+function seojuice_pin_key() {
+    $keys = seojuice_active_seo_title_keys();
+    return $keys ? $keys[0] : SEOJUICE_PIN_KEY;
+}
+
+// Returns the post meta string for $key on a singular front-end view of its post, or ''.
+function seojuice_title_meta_for_view($key) {
+    if (is_admin() || is_feed() || !is_singular()) { return ''; }
+    $id = (int) get_queried_object_id();
+    if ($id <= 0) { return ''; }
+    return (string) get_post_meta($id, $key, true);
+}
+
+function seojuice_filter_pre_document_title($title) {
+    $v = seojuice_title_meta_for_view(SEOJUICE_OWN_TITLE_KEY);
+    if ($v === '' || seojuice_pin_capable() !== 'core') { return $title; }
+    return $v;
+}
+add_filter('pre_get_document_title', 'seojuice_filter_pre_document_title', SEOJUICE_TITLE_PRIORITY);
+
+function seojuice_filter_document_title_parts($parts) {
+    // Core builds a static front page title from site name and tagline, not post_title.
+    if (is_front_page()) { return $parts; }
+    if (seojuice_title_meta_for_view(SEOJUICE_OWN_TITLE_KEY) !== '') { return $parts; }
+    $pin = seojuice_title_meta_for_view(SEOJUICE_PIN_KEY);
+    if ($pin === '' || seojuice_pin_capable() !== 'core') { return $parts; }
+    if (!is_array($parts)) { $parts = array(); }
+    $parts['title'] = $pin;
+    return $parts;
+}
+add_filter('document_title_parts', 'seojuice_filter_document_title_parts', SEOJUICE_TITLE_PRIORITY);
+
 function seojuice_capabilities() {
-    $caps = array('persistent_apply', 'footer_backlink', 'url_replace', 'cache_clear', 'apply_reasons', 'content_save_guard', 'seo_title');
+    $caps = array('persistent_apply', 'footer_backlink', 'url_replace', 'cache_clear', 'apply_reasons', 'content_save_guard', 'seo_title', 'headline');
     if (SEOJUICE_CAP_ALT_INLINE) {
         $caps[] = 'alt_inline';
@@ -2521 +2620 @@
             'title' => $post->post_title,
             'seo_title' => seojuice_read_seo_title($post_id),
+            'h1_raw' => seojuice_read_h1_raw($post),
             'status' => $post->post_status,
             'url' => get_permalink($post->ID),
@@ -3590 +3690 @@
 }
 
+// ---------------------------------------------------------------------------
+// headline: change the page heading (H1) without moving the search title.
+// ---------------------------------------------------------------------------
+
+// Comparison form of a heading: tags stripped, entities decoded, typographic
+// quotes/dashes folded to ASCII, whitespace collapsed.
+function seojuice_headline_norm($s): string {
+    $s = html_entity_decode(strip_tags((string) $s), ENT_QUOTES | ENT_HTML5, 'UTF-8');
+    $s = strtr($s, array(
+        "\u{2018}" => "'", "\u{2019}" => "'", "\u{201B}" => "'", "\u{2032}" => "'",
+        "\u{201C}" => '"', "\u{201D}" => '"', "\u{201E}" => '"', "\u{2033}" => '"',
+        "\u{2013}" => '-', "\u{2014}" => '-', "\u{2026}" => '...', "\u{00A0}" => ' ',
+    ));
+    return trim((string) preg_replace('/\s+/u', ' ', $s));
+}
+
+// Parses a body into a wrapper element; null on failure.
+function seojuice_headline_parse(string $content): ?array {
+    $dom = new DOMDocument();
+    $prev = libxml_use_internal_errors(true);
+    $dom->loadHTML('<?xml encoding="UTF-8" ?><div id="seojuice-root">' . $content . '</div>',
+        LIBXML_HTML_NOIMPLIED | LIBXML_HTML_NODEFDTD);
+    libxml_clear_errors(); libxml_use_internal_errors($prev);
+    $root = $dom->getElementById('seojuice-root');
+    return $root ? array($dom, $root) : null;
+}
+
+function seojuice_elementor_has_h1($nodes, array $wanted): bool {
+    if (!is_array($nodes)) { return false; }
+    foreach ($nodes as $n) {
+        if (!is_array($n)) { continue; }
+        if (($n['widgetType'] ?? '') === 'heading'
+            && strtolower((string) ($n['settings']['header_size'] ?? '')) === 'h1'
+            && isset($wanted[seojuice_headline_norm($n['settings']['title'] ?? '')])) {
+            return true;
+        }
+        if (!empty($n['elements']) && seojuice_elementor_has_h1($n['elements'], $wanted)) { return true; }
+    }
+    return false;
+}
+
+// True when a page builder owns the visible H1: writing post_title there would rename
+// menus and leave the heading unchanged.
+function seojuice_headline_in_builder(int $post_id, string $content, array $wanted): bool {
+    if (get_post_meta($post_id, '_fl_builder_enabled', true)) { return true; }
+    $el = get_post_meta($post_id, '_elementor_data', true);
+    if (is_string($el) && $el !== '') { $el = json_decode($el, true); }
+    if (seojuice_elementor_has_h1($el, $wanted)) { return true; }
+    if (strpos($content, '[vc_custom_heading') !== false
+        && preg_match_all('/\[vc_custom_heading\b([^\]]*)\]/', $content, $sc)) {
+        foreach ($sc[1] as $attrs) {
+            if (!preg_match_all('/(\w+)\s*=\s*"([^"]*)"/', $attrs, $kv, PREG_SET_ORDER)) { continue; }
+            $a = array();
+            foreach ($kv as $pair) { $a[$pair[1]] = $pair[2]; }
+            $fc = urldecode($a['font_container'] ?? '');
+            if (preg_match('/(^|\|)tag:h1(\||$)/i', $fc) && isset($wanted[seojuice_headline_norm(urldecode($a['text'] ?? ''))])) {
+                return true;
+            }
+        }
+    }
+    return false;
+}
+
+// Content <h1> elements whose text matches $wanted: array('count' => n, 'text' => raw text
+// of the single match, 'targetable' => the diff engine would edit that very element).
+function seojuice_headline_content_h1(string $content, array $wanted): array {
+    $out = array('count' => 0, 'text' => '', 'targetable' => false);
+    $parsed = seojuice_headline_parse($content);
+    if (!$parsed) { return $out; }
+    list($dom, $root) = $parsed;
+    $match = null;
+    foreach ($dom->getElementsByTagName('h1') as $h) {
+        if (isset($wanted[seojuice_headline_norm($h->textContent)])) { $out['count']++; $match = $h; }
+    }
+    if ($out['count'] !== 1) { return $out; }
+    $out['text'] = $match->textContent;
+    $t = seojuice_locate_diff_target($dom, $root, 'h1', $out['text']);
+    for ($n = $t; $n instanceof DOMNode; $n = $n->parentNode) {
+        if ($n->isSameNode($match)) { $out['targetable'] = true; break; }
+    }
+    return $out;
+}
+
+// Raw text the page shows as its H1: the single content <h1>, else raw post_title.
+// Never get_the_title(), which wptexturize alters.
+function seojuice_read_h1_raw($post): string {
+    $parsed = seojuice_headline_parse((string) $post->post_content);
+    if ($parsed) {
+        $h1s = $parsed[0]->getElementsByTagName('h1');
+        if ($h1s->length === 1) { return trim((string) $h1s->item(0)->textContent); }
+    }
+    return (string) $post->post_title;
+}
+
+function seojuice_default_title_template(string $key, string $post_type): string {
+    $pt = $post_type !== '' ? $post_type : 'post';
+    if ($key === '_yoast_wpseo_title') {
+        $o = get_option('wpseo_titles', array());
+        $t = is_array($o) && isset($o['title-' . $pt]) ? (string) $o['title-' . $pt] : '';
+        return $t !== '' ? $t : '%%title%% %%page%% %%sep%% %%sitename%%';
+    }
+    if ($key === 'rank_math_title') {
+        $o = get_option('rank_math_titles', array());
+        $t = is_array($o) && isset($o['pt_' . $pt . '_title']) ? (string) $o['pt_' . $pt . '_title'] : '';
+        return $t !== '' ? $t : '%title% %sep% %sitename%';
+    }
+    $o = get_option('seopress_titles_option_name', array());
+    $t = is_array($o) && isset($o['seopress_titles_single_titles'][$pt]['title'])
+        ? (string) $o['seopress_titles_single_titles'][$pt]['title'] : '';
+    return $t !== '' ? $t : '%%post_title%% - %%sitetitle%%';
+}
+
+// Pin values to hold the search title steady across a post_title write: key => value
+// to store. A value equal to the live one means no pin is needed (or one already holds).
+function seojuice_headline_pin_values(int $post_id, string $mode, string $old_title, string $post_type): array {
+    $vars = array('%%title%%', '%title%', '%%post_title%%');
+    $out = array();
+    if ($mode === 'core') {
+        $cur = (string) get_post_meta($post_id, SEOJUICE_PIN_KEY, true);
+        $own = (string) get_post_meta($post_id, SEOJUICE_OWN_TITLE_KEY, true);
+        // An earlier pin already holds the pre-heading title; an approved search title
+        // overrides the whole <title>, so the pin is not needed while it is live.
+        $out[SEOJUICE_PIN_KEY] = ($cur !== '' || $own !== '') ? $cur : $old_title;
+        return $out;
+    }
+    foreach (seojuice_active_seo_title_keys() as $key) {
+        $cur = (string) get_post_meta($post_id, $key, true);
+        $tpl = $cur !== '' ? $cur : seojuice_default_title_template($key, $post_type);
+        $has = false;
+        foreach ($vars as $v) { if (strpos($tpl, $v) !== false) { $has = true; break; } }
+        $out[$key] = $has ? str_replace($vars, $old_title, $tpl) : $cur;
+    }
+    return $out;
+}
+
+// Applies one `headline` change. Returns array('result', 'reason', 'target', 'content',
+// 'content_dirty'). Resolution order: page builder, single content <h1>, raw post_title.
+function seojuice_apply_headline(int $post_id, string $content, int $cs_id, array $payload, bool $save_unsafe): array {
+    $res = array('result' => 'skipped', 'reason' => '', 'target' => '', 'content' => $content, 'content_dirty' => false);
+    $new = isset($payload['h1']) && is_string($payload['h1']) ? sanitize_text_field($payload['h1']) : '';
+    $wanted = array();
+    foreach (array('expected_h1', 'crawled_h1') as $k) {
+        $n = isset($payload[$k]) && is_string($payload[$k]) ? seojuice_headline_norm($payload[$k]) : '';
+        if ($n !== '') { $wanted[$n] = true; }
+    }
+    if ($new === '' || !$wanted) { $res['reason'] = 'invalid_payload'; return $res; }
+    if (seojuice_headline_in_builder($post_id, $content, $wanted)) { $res['reason'] = 'h1_in_page_builder'; return $res; }
+
+    $h1 = seojuice_headline_content_h1($content, $wanted);
+    if ($h1['count'] === 1) {
+        if (!$h1['targetable']) { $res['reason'] = 'unlocatable'; return $res; }
+        if ($save_unsafe) { $res['reason'] = 'content_unsafe_to_save'; return $res; }
+        $d = seojuice_apply_content_diff($content, $cs_id, array(
+            'location_dom' => 'h1', 'original_text' => $h1['text'], 'operation' => 'replace',
+            'text' => htmlspecialchars($new, ENT_QUOTES | ENT_SUBSTITUTE, 'UTF-8'),
+        ));
+        if (!$d['applied']) { $res['reason'] = 'unlocatable'; return $res; }
+        seojuice_record_content_diff_version($post_id, $cs_id, $d['before']);
+        return array('result' => 'applied', 'reason' => '', 'target' => 'content_h1',
+            'content' => $d['content'], 'content_dirty' => true);
+    }
+    $post = get_post($post_id);
+    if ($h1['count'] > 1 || !$post || !isset($wanted[seojuice_headline_norm($post->post_title)])) {
+        $res['reason'] = 'h1_not_found';
+        return $res;
+    }
+
+    // A static posts page builds its <title> from single_post_title(), so no pin renders.
+    $mode = seojuice_pin_capable();
+    if ((int) get_option('page_for_posts', 0) === $post_id || $mode === 'unsupported') {
+        $res['reason'] = 'title_would_change';
+        return $res;
+    }
+    // wp_update_post re-saves the stored body through the save filters, so a body kses would strip must not be touched.
+    if ($save_unsafe) { $res['reason'] = 'content_unsafe_to_save'; return $res; }
+    $old_title = (string) $post->post_title;
+    $pins = seojuice_headline_pin_values($post_id, $mode, $old_title, (string) ($post->post_type ?? 'post'));
+    $before = array(); $wrote = array();
+    foreach ($pins as $key => $value) {
+        $present = metadata_exists('post', $post_id, $key);
+        $cur = (string) get_post_meta($post_id, $key, true);
+        $before[$key] = array('present' => $present, 'value' => $cur);
+        if ($value !== $cur) { seojuice_update_post_meta($post_id, $key, $value); }
+        $wrote[$key] = $value;
+    }
+    $updated = seojuice_update_post(array('ID' => $post_id, 'post_title' => $new), true);
+    if (is_wp_error($updated) || !$updated) {
+        foreach ($before as $key => $b) {
+            if ($b['present']) { seojuice_update_post_meta($post_id, $key, $b['value']); }
+            else { delete_post_meta($post_id, $key); }
+        }
+        $res['reason'] = 'update_failed';
+        return $res;
+    }
+    $after = get_post($post_id);
+    $wrote_title = $after ? (string) $after->post_title : $new;
+    seojuice_record_field_version($post_id, $cs_id, 'post_title', $old_title, $wrote_title, $before, $wrote);
+    $res['result'] = 'applied';
+    $res['target'] = 'post_title';
+    return $res;
+}
+
 function seojuice_rest_apply_changes($request) {
     $post_id = intval($request->get_param('id'));
@@ -3613 +3915 @@
     $results      = array();
     $reasons      = array();
+    $targets      = array();
     $persisted_ids = array();
     $alt_commits   = array();
@@ -3705 +4008 @@
         } elseif ($type === 'seo_title') {
             $new = isset($payload['title']) ? sanitize_text_field($payload['title']) : '';
-            $keys = seojuice_active_seo_title_keys();
+            $mode = seojuice_pin_capable();
+            $keys = $mode === 'core' ? array(SEOJUICE_OWN_TITLE_KEY) : seojuice_active_seo_title_keys();
             if ($new === '') {
                 $results[(string) $cs_id] = 'skipped';
@@ -3724 +4028 @@
                 $persisted_ids[] = $cs_id;
             }
+        } elseif ($type === 'headline') {
+            if ($save_unsafe === null) {
+                $save_unsafe = seojuice_save_would_strip_content((string) $owned->post_content);
+            }
+            $res = seojuice_apply_headline($post_id, $content, $cs_id, $payload, $save_unsafe);
+            $results[(string) $cs_id] = $res['result'];
+            if ($res['result'] === 'applied') {
+                $content       = $res['content'];
+                $content_dirty = $content_dirty || $res['content_dirty'];
+                $targets[(string) $cs_id] = $res['target'];
+                $persisted_ids[] = $cs_id;
+            } else {
+                $reasons[(string) $cs_id] = $res['reason'];
+            }
         } elseif ($type === 'og') {
             $map = array(
@@ -3831 +4149 @@
     }
 
-    return new WP_REST_Response(array('success' => true, 'results' => $results, 'reasons' => $reasons), 200);
+    return new WP_REST_Response(array('success' => true, 'results' => $results, 'reasons' => $reasons, 'targets' => $targets), 200);
 }
 
@@ -3848 +4166 @@
     $reverted = array();
     $outcomes = array();
+    $key_outcomes = array();
 
     foreach ($ids as $cs_id) {
@@ -3902 +4221 @@
             $outcome = $res['outcome'] ?? 'absent';
         }
+        // Per-key results for title, heading and meta changes; their change-level
+        // outcome was always 'absent' before, which hid a kept client edit.
+        $ko = (isset($res['key_outcomes']) && is_array($res['key_outcomes'])) ? $res['key_outcomes'] : array();
+        if ($ko) {
+            $key_outcomes[(string) $cs_id] = $ko;
+            if ($outcome === null || $outcome === 'absent') {
+                $outcome = in_array('kept_edit', $ko, true) ? 'drift_kept' : 'restored';
+            }
+        }
         if ($blocked) {
             $outcome = 'blocked';
@@ -3916 +4244 @@
     }
 
-    return new WP_REST_Response(array('success' => true, 'reverted' => $reverted, 'outcomes' => $outcomes), 200);
+    return new WP_REST_Response(array('success' => true, 'reverted' => $reverted, 'outcomes' => $outcomes, 'key_outcomes' => $key_outcomes), 200);
 }