. "Safely" * carries a lot of weight — a naive str_replace over 300 hand-written posts * would corrupt shortcode attributes, nest anchors, rewrite alt text and break * Gutenberg block delimiters, and the user would not discover it for weeks. * * Two lessons are inherited from the in-body image work in the main plugin: * * 1. Never assume

exists. Classic-editor content stores paragraphs as * bare text between block elements and lets wpautop() create the

at * render time — a real post can contain zero

in post_content. This is * the same trap documented at aicobr_prose_anchor_offset(); a linker that * anchors on paragraphs silently no-ops on exactly the older hand-written * posts this feature exists to serve. * * 2. Apply edits from the HIGHEST offset backwards, so earlier offsets stay * valid as the string grows. Same discipline as aicobr_insert_figure(). * * Offsets are BYTE offsets, consistent with preg_* PREG_OFFSET_CAPTURE and with * aicobr_find_headings() in the main plugin. Multibyte safety comes from every * pattern carrying the /u flag, so a match can only ever begin and end on a * character boundary — never from mb_* string juggling, which would disagree * with the rest of the codebase. */ if (!class_exists('AICOBR_Link_Scanner')) { class AICOBR_Link_Scanner { /** * Elements whose ENTIRE contents are off limits, not merely their tags. * * a — anchors cannot nest, and re-linking existing link text is * both invalid HTML and an over-optimisation signal. * h1..h6 — linking a heading reads as spam and breaks the visual * hierarchy the formatter builds. * figure — covers

, including ACB's own acb-fig captions. * code/pre/ — a keyword inside a code sample is not prose. * kbd/samp * script/ — self-evident; also protects inline JSON. * style * blockquote — inserting a link into quoted material silently alters * somebody else's words. Editorially wrong rather than * technically unsafe, so it is filterable, but the default * is to leave quotations alone. * textarea/ — these hold TEXT that is not prose. An inside

* title/ renders as literal characters in a form field; inside
 * svg/ <title> or <svg> it is invalid. Rare in post_content, but
 * iframe/ a pasted embed or form plugin puts them there, and the
 * noscript cost of listing them is nil.
 */
 const PAIRED_UNSAFE = [
 'a', 'h1', 'h2', 'h3', 'h4', 'h5', 'h6',
 'figure', 'code', 'pre', 'kbd', 'samp',
 'script', 'style', 'blockquote',
 'textarea', 'title', 'svg', 'iframe', 'noscript',
 ];

/**
     * Byte ranges that must never be touched, as a merged, ascending list of
     * [start, end) pairs.
     *
     * Built from four passes rather than one clever regex, because each pass is
     * separately explainable and separately testable, and because merging makes
     * pass order irrelevant.
     */
    public static function unsafe_ranges($html) {
        $html   = (string) $html;
        $ranges = [];

// Pass 1 — HTML comments. Must come before the generic tag pass: a
 // Gutenberg delimiter such as 
 // legitimately contains '>', which the tag pattern would truncate at.
 // Both ranges are collected and merged, so the comment always wins.
 //
 // An UNTERMINATED comment runs to the end of the document, exactly as an
 // unclosed paired tag does. A browser swallows everything after a stray
 // '', $open + 4);
 $end = ($close === false) ? $len : $close + 3;
 $ranges[] = [$open, $end];
 if ($close === false) break;
 $at = $end;
 }

// Pass 2 — every tag, which is what protects ATTRIBUTE VALUES. A phrase
 // occurring in alt="sell my van" or title="..." or inside an href sits
 // within these bounds and is therefore excluded without needing to be
 // parsed as an attribute at all.
 if (preg_match_all('/<[^>]*>/su', $html, $m, PREG_OFFSET_CAPTURE)) {
 foreach ($m[0] as $hit) {
 $ranges[] = [$hit[1], $hit[1] + strlen($hit[0])];
 }
 }

// Pass 3 — shortcodes, including their attributes. A match inside
        // [content_image alt="sell my van"] would corrupt the shortcode.
        // Deliberately covers the BRACKETS ONLY: the body of an enclosing
        // shortcode is ordinary prose and stays linkable.
        //
        // Quoted attribute values are consumed as a unit so that BRACKETS INSIDE
        // A QUOTED VALUE do not end the shortcode early. [gallery ids="[1,2]"
        // alt="sell my van"] is the case that matters: a naive [^\][]* stops at
        // the inner ']' and leaves the alt text exposed and linkable.
        $shortcode = '/\['                       // opening bracket
                   . '(?:'
                   .   '"[^"]*"'                 // "…" may contain [ or ]
                   .   "|'[^']*'"                // '…' likewise
                   .   '|[^\]\[\'"]'             // any other non-bracket char
                   . ')*'
                   . '\]/su';
        if (preg_match_all($shortcode, $html, $m, PREG_OFFSET_CAPTURE)) {
            foreach ($m[0] as $hit) {
                $ranges[] = [$hit[1], $hit[1] + strlen($hit[0])];
            }
        }

// Pass 4 — paired elements, contents included.
        foreach (self::PAIRED_UNSAFE as $tag) {
            foreach (self::paired_ranges($html, $tag) as $r) {
                $ranges[] = $r;
            }
        }

return self::merge_ranges($ranges);
    }

/**
 * Ranges spanned by <$tag …> … </$tag>, contents included.
 *
 * Scanned sequentially rather than with a lazy .*? pair, so that an UNCLOSED
 * tag can be handled conservatively: if no closing tag is found, the range
 * runs to the end of the document. Malformed markup is common in a decade
 * old back catalogue, and the failure mode has to be "link nothing" rather
 * than "link inside a stray anchor".
 *
 * Self-closing and void forms (<a … />) open nothing and are already covered
 * by the generic tag pass.
 */
 private static function paired_ranges($html, $tag) {
 $out = [];
 $len = strlen($html);
 $off = 0;

$open = '/<' . $tag . '\b[^>]*?(\/)?>/iu';
 $close = '/<\/' . $tag . '\s*>/iu';

while ($off < $len && preg_match($open, $html, $om, PREG_OFFSET_CAPTURE, $off)) {
 $start = $om[0][1];
 $after = $start + strlen($om[0][0]);

// <tag /> — self-closing, nothing enclosed.
 if (!empty($om[1][0])) { $off = $after; continue; }

if (preg_match($close, $html, $cm, PREG_OFFSET_CAPTURE, $after)) {
                $end = $cm[0][1] + strlen($cm[0][0]);
            } else {
                $end = $len;                 // unclosed — refuse the remainder
            }

$out[] = [$start, $end];
            $off   = ($end > $after) ? $end : $after;
        }

return $out;
    }

/** Merge overlapping/adjacent ranges into an ascending, disjoint list. */
 private static function merge_ranges($ranges) {
 if (!$ranges) return [];
 usort($ranges, fn($a, $b) => $a[0] <=> $b[0] ?: $a[1] <=> $b[1]);

$out = [];
 $cur = $ranges[0];
 for ($i = 1, $n = count($ranges); $i < $n; $i++) {
 if ($ranges[$i][0] <= $cur[1]) {
 if ($ranges[$i][1] > $cur[1]) $cur[1] = $ranges[$i][1];
 } else {
 $out[] = $cur;
 $cur = $ranges[$i];
 }
 }
 $out[] = $cur;
 return $out;
 }

/** True when [start, end) overlaps no unsafe range. */
 private static function is_safe($start, $end, $ranges) {
 foreach ($ranges as $r) {
 if ($start < $r[1] && $end > $r[0]) return false;
 if ($r[0] >= $end) break; // ranges are ascending
 }
 return true;
 }

/**
     * Turn a phrase into a word-boundary pattern.
     *
     * Boundaries are expressed as lookarounds over letters/digits/underscore
     * rather than \b, because \b is not Unicode-aware in the way needed here:
     * with /u it would still treat an accented character inconsistently at the
     * edges. This form guarantees "van" cannot match inside "vanguard",
     * "advantage" or "Vansittart".
     *
     * Inter-word whitespace is matched loosely — runs of whitespace, and the
     *   entity, both occur between words in real stored content and a
     * literal single space would miss them.
     */
    private static function phrase_pattern($phrase) {
        $words = preg_split('/\s+/u', trim((string) $phrase), -1, PREG_SPLIT_NO_EMPTY);
        if (!$words) return '';

$parts = array_map(fn($w) => preg_quote($w, '/'), $words);
        $body  = implode('(?:\s| | )+', $parts);

return '/(?<![\p{L}\p{N}_])' . $body . '(?![\p{L}\p{N}_])/iu';
 }

/**
     * AICOBR_NAME_GUARD_2026_08
     *
     * Normalise a name for comparison: lower-cased, punctuation to whitespace.
     * Mirrors aicobr_normalise_key() in acb-strategist.php and normaliseKey() in
     * the server's lib/anchor-variants.js, so "Mercedes-Benz Vito" compares equal
     * however it was typed.
     */
    public static function name_key($s) {
        $s = function_exists('mb_strtolower') ? mb_strtolower((string) $s, 'UTF-8') : strtolower((string) $s);
        $s = preg_replace('/[^a-z0-9]+/', ' ', $s);
        return trim($s);
    }

/**
     * AICOBR_NAME_GUARD_2026_08
     *
     * name_key with a single leading determiner removed, for COMPARISON ONLY —
     * the phrase itself is never rewritten.
     *
     * Without this the guard silently does nothing for exactly the variants that
     * need it most. A variant reads "the Ford Transit", every published name reads
     * "Ford Transit Custom", and "ford transit custom review" does not begin with
     * "the ford transit " — so no extender is ever derived and every split is
     * waved through. The server's scrubSiblingVariants() learned this same lesson
     * (coreKey in lib/anchor-variants.js); it has to hold at match time too.
     */
    public static function core_key($s) {
        return preg_replace('/^(?:the|a|an)\s+/', '', self::name_key($s));
    }

/**
 * AICOBR_NAME_GUARD_2026_08
 *
 * Would linking [start,end) split a longer name the site already publishes?
 *
 * The problem this solves is inherent to exact-phrase linking, not to any one
 * implementation: "Ford Transit" is a word-boundary match INSIDE "Ford Transit
 * Custom", because the boundary after "Transit" is a space. Every phrase-based
 * linker has this; the usual answers are a language model guessing that
 * Transit Custom is its own product, or a human catching it at review.
 *
 * ACB can do better than either, because the user already DECLARED the names:
 * sibling keywords and published post titles say what the longer products are.
 * So the decision is made per OCCURRENCE and stays deterministic — "Ford
 * Transit" links happily in "the Ford Transit is a workhorse" and is refused
 * in "the Ford Transit Custom", from one variant, with no model and no credits.
 *
 * Reads forward through DISPLAY text (tags flattened) so intervening markup —
 * "Ford Transit Custom" — cannot smuggle a split past the
 * guard. Stops at the first token that normalises to nothing, which is how
 * sentence boundaries end a name: "the Ford Transit. Custom vans…" is two
 * sentences, not a product.
 *
 * @param array $extenders Normalised names STRICTLY LONGER than the phrase and
 * beginning with it. See AICOBR_Inbound_Links::extenders().
 */
 public static function splits_longer_name($html, $end, $matched_text, array $extenders, $lookahead = 4) {
 if (!$extenders) return false;

// Both forms: "the ford transit" as written, and "ford transit" as the
        // catalogue names it. A published name may extend either.
        $bases = [];
        foreach ([self::name_key($matched_text), self::core_key($matched_text)] as $b) {
            if ($b !== '' && !in_array($b, $bases, true)) $bases[] = $b;
        }
        if (!$bases) return false;

$tail  = self::flatten(substr((string) $html, $end, 200));
        $raw   = preg_split('/\s+/u', trim($tail), -1, PREG_SPLIT_NO_EMPTY) ?: [];

$steps = 0;
        foreach ($raw as $token) {
            // A token that normalises to nothing is punctuation standing alone —
            // the name has ended. "the Ford Transit. Custom shelving…" is two
            // sentences, not a product.
            $norm = self::name_key($token);
            if ($norm === '') return false;

// One normalised WORD at a time, because a single token can carry more
            // than one: "Custom's" normalises to "custom s", and appending it whole
            // produced "ford transit custom s", which prefix-matches no real name —
            // so every possessive form of a product name slipped the guard. Live
            // content is full of them ("the Ford Transit Custom's payload").
            foreach (preg_split('/\s+/', $norm, -1, PREG_SPLIT_NO_EMPTY) as $w) {
                foreach ($bases as $bi => $base) {
                    $bases[$bi] = $base . ' ' . $w;
                    foreach ($extenders as $name) {
                        if ($name === $bases[$bi] || strpos($name, $bases[$bi] . ' ') === 0) return true;
                    }
                }
                if (++$steps >= $lookahead) return false;
            }
        }
        return false;
    }

/**
 * Every safe occurrence of $phrase, in document order.
 *
 * @param int $limit 0 = all. Callers normally pass 1: repeat-linking the
 * same phrase within one post is a textbook
 * over-optimisation signal.
 * @param array $extenders AICOBR_NAME_GUARD_2026_08 — longer published names
 * beginning with this phrase. An occurrence that runs
 * on into one of them is refused, so a link can never
 * wrap the front slice of a longer product name.
 * @return array<int, array{start:int,end:int,text:string}>
 */
 public static function find_matches($html, $phrase, $limit = 0, array $extenders = []) {
 $html = (string) $html;
 $pattern = self::phrase_pattern($phrase);
 if ($pattern === '' || $html === '') return [];

if (!preg_match_all($pattern, $html, $m, PREG_OFFSET_CAPTURE)) return [];

$unsafe = self::unsafe_ranges($html);
        $out    = [];

foreach ($m[0] as $hit) {
            $start = $hit[1];
            $end   = $start + strlen($hit[0]);
            if (!self::is_safe($start, $end, $unsafe)) continue;
            if (self::splits_longer_name($html, $end, $hit[0], $extenders)) continue;

$out[] = ['start' => $start, 'end' => $end, 'text' => $hit[0]];
            if ($limit > 0 && count($out) >= $limit) break;
        }

return $out;
    }

/**
     * Does $phrase occur at all, ignoring whether the spot is safe to link?
     *
     * AICOBR_ABSENT_VS_UNSAFE_2026_08
     *
     * find_matches() answers "where can I safely link this?", and returns nothing
     * for two very different reasons: the phrase is not in the document, or it is
     * there but every occurrence sits in a heading, an existing link, a caption or
     * a quote. Those demand opposite responses from the user — rewrite the anchor
     * phrase, versus accept that the guard is doing its job — so the caller needs
     * to tell them apart rather than reporting one and meaning either.
     *
     * Cheap: the pattern match runs first and unsafe_ranges() is never computed.
     */
    public static function occurs($html, $phrase) {
        $html    = (string) $html;
        $pattern = self::phrase_pattern($phrase);
        if ($pattern === '' || $html === '') return false;
        return (bool) preg_match($pattern, $html);
    }

/**
     * True when $html already links to $url.
     *
     * Mirrors the trailing-slash and entity tolerance of the cluster link count
     * in handle_publish, which learned the hard way that a stored href may be
     * entity-encoded and may or may not carry a trailing slash.
     */
    public static function links_to($html, $url) {
        $needle   = rtrim((string) $url, '/');
        if ($needle === '') return false;
        $haystack = html_entity_decode((string) $html, ENT_QUOTES, 'UTF-8');

// AICOBR_LINK_BOUNDARY_2026_08
        // A prefix match is not enough, and neither is "the next character is a
        // slash". Two real cases from one live site:
        //
        //   1. /we-buy-any-van/ vs /we-buy-any-van-in-birmingham/
        //      A location page EXTENDS the pillar's path. Prefix matching
        //      counted every link to a location page as a link to the pillar.
        //
        //   2. The pillar IS the homepage, https://site.co.uk with no path.
        //      Every internal absolute link on the site begins with that string,
        //      so accepting a following "/" as a boundary matched
        //      href="https://site.co.uk/sell-my-van/" as a link to the homepage.
        //      The pillar reported 226 inbound links; almost none were real.
        //
        // So a slash only ends the URL when the URL ends there: it must be
        // followed by the closing quote, a query, a fragment, or nothing. A
        // slash followed by anything else is a DEEPER PATH, which is a different
        // page. Same lesson as the name guard: one identifier being a prefix of
        // another needs a real boundary, not a plausible-looking one.
        $ends = function ($c) {
            return $c === '"' || $c === "'" || $c === '?' || $c === '#' || $c === '';
        };

foreach (['href="', "href='"] as $attr) {
            $quote = substr($attr, -1);
            $at    = 0;
            while (($pos = strpos($haystack, $attr . $needle, $at)) !== false) {
                $i     = $pos + strlen($attr) + strlen($needle);
                $after = substr($haystack, $i, 1);

if ($after === $quote || $after === '?' || $after === '#' || $after === '') {
                    return true;                       // exact, no trailing slash
                }
                if ($after === '/' && $ends(substr($haystack, $i + 1, 1))) {
                    return true;                       // exact, trailing slash
                }
                $at = $pos + 1;                        // deeper path: keep looking
            }
        }
        return false;
    }

/**
     * Apply link insertions to content.
     *
     * @param array $insertions Each ['start'=>int,'end'=>int,'url'=>string,
     *                          'title'=>?string,'class'=>?string]
     *
     * Applied from the highest offset DOWNWARDS so that every earlier offset
     * remains valid as the string grows — the same reason aicobr_insert_figure()
     * works backwards. Overlapping insertions are dropped rather than merged:
     * two links claiming the same words is a caller bug, and silently producing
     * nested anchors would be worse than refusing one of them.
     */
    public static function apply_links($html, array $insertions) {
        $html = (string) $html;
        if (!$insertions) return $html;

usort($insertions, fn($a, $b) => $b['start'] <=> $a['start']);

$lastStart = null;
 foreach ($insertions as $ins) {
 $start = (int) $ins['start'];
 $end = (int) $ins['end'];
 if ($start < 0 || $end > strlen($html) || $end <= $start) continue;
 if ($lastStart !== null && $end > $lastStart) continue; // overlaps

$anchor = substr($html, $start, $end - $start);
            $html   = substr($html, 0, $start)
                    . self::build_anchor($ins['url'], $anchor, $ins['title'] ?? '', $ins['class'] ?? '')
                    . substr($html, $end);

$lastStart = $start;
        }

return $html;
    }

/**
 * The <a> ACB writes.
 *
 * Carries a class so its links are identifiable in content later — for
 * counting, for reporting, and above all for undo, which must be able to
 * find exactly what ACB wrote and nothing a user wrote by hand.
 */
 public static function build_anchor($url, $text, $title = '', $class = 'acb-ilink') {
 $class = $class !== '' ? $class : 'acb-ilink';
 $attrs = 'href="' . self::esc_attr($url) . '" class="' . self::esc_attr($class) . '"';
 if ($title !== '') $attrs .= ' title="' . self::esc_attr($title) . '"';
 return '<a ' . $attrs . '>' . $text . '</a>';
 }

/**
     * Reverse one ACB link, restoring the original anchor text.
     *
     * Matched on the exact stored HTML. If it is not found the post has been
     * edited since insertion, and this REFUSES rather than falling back to a
     * looser pattern — a blind regex over content a user has since rewritten is
     * precisely the failure this feature must not have.
     *
     * @return string|false New content, or false when the link was not found.
     */
    public static function remove_link($html, $stored_html) {
        $html        = (string) $html;
        $stored_html = (string) $stored_html;
        if ($stored_html === '') return false;

$at = strpos($html, $stored_html);
        if ($at === false) return false;

if (!preg_match('/^<a\b[^>]*>(.*)<\/a>$/su', $stored_html, $m)) return false;

return substr($html, 0, $at) . $m[1] . substr($html, $at + strlen($stored_html));
    }

/**
 * Plain-text excerpt around a match, for the approval UI.
 *
 * Seeing the sentence a link will land in is what makes review meaningful
 * rather than a list of post titles clicked through blindly. Tags are
 * stripped for display and the anchor is wrapped in , so the caller
 * renders a highlight without re-deriving the offset.
 *
 * mb_* is used HERE and only here: this is display text that gets truncated
 * at an arbitrary width, so it is the one place a naive byte cut could split
 * a character and emit mojibake.
 */
 public static function excerpt($html, $start, $end, $pad = 70) {
 $before = self::flatten(substr($html, 0, $start));
 $anchor = self::flatten(substr($html, $start, $end - $start));
 $after = self::flatten(substr($html, $end));

$bLen = self::mb_len($before);
        $lead = $bLen > $pad ? '…' . self::mb_cut($before, $bLen - $pad, $pad) : $before;
        $tail = self::mb_len($after) > $pad ? self::mb_cut($after, 0, $pad) . '…' : $after;

return trim($lead) . '' . $anchor . '' . rtrim($tail);
 }

/**
     * AICOBR_RESCAN_CONTEXT_2026_08
     *
     * A normalised fingerprint of the text immediately around a matched range,
     * used to identify WHICH occurrence of a phrase the user reviewed. Built from
     * flattened display text (tags out, entities decoded, whitespace collapsed)
     * and lower-cased — the SAME text the excerpt shows — so it is stable across
     * cosmetic markup changes but sensitive to real edits of the surrounding
     * words.
     *
     * Produced at review time (travels with the suggestion) and recomputed at
     * insert time; identity is "same window on both sides". Producer and consumer
     * MUST use the same $window.
     *
     * @return array{before:string, after:string}
     */
    public static function occurrence_context($html, $start, $end, $window = 48) {
        $html   = (string) $html;
        $start  = max(0, (int) $start);
        $end    = max($start, (int) $end);

$before = self::flatten(substr($html, 0, $start));
        $after  = self::flatten(substr($html, $end));

$bLen   = self::mb_len($before);
        $before = $bLen > $window ? self::mb_cut($before, $bLen - $window, $window) : $before;
        $after  = self::mb_len($after) > $window ? self::mb_cut($after, 0, $window) : $after;

return ['before' => self::ctx_norm($before), 'after' => self::ctx_norm($after)];
    }

/** Normalise a context window: collapse whitespace, lower-case, trim. */
    private static function ctx_norm($s) {
        $s = preg_replace('/\s+/u', ' ', (string) $s);
        $s = function_exists('mb_strtolower') ? mb_strtolower($s, 'UTF-8') : strtolower($s);
        return trim($s);
    }

/**
     * AICOBR_RESCAN_CONTEXT_2026_08
     *
     * Re-find, in CURRENT content, the specific SAFE occurrence of $phrase the
     * user reviewed — identified by $context (what occurrence_context() returned
     * at review time). Returns the match ['start','end','text'] only when a
     * currently-safe occurrence has the SAME surrounding context; returns null
     * otherwise: the occurrence was deleted, has moved into an unsafe spot
     * (heading, existing link, …), or the words around it were edited.
     *
     * This is the insert-time guard that makes placement correct-or-nothing. The
     * byte offset cached at scan time is never trusted — the phrase is re-located
     * against live content and a link is only ever written where the reviewed
     * sentence still is. No match → the caller writes nothing and tells the user
     * to re-scan.
     *
     * @param array{before?:string, after?:string} $context
     * @return array{start:int,end:int,text:string}|null
     */
    public static function find_reviewed_occurrence($html, $phrase, $context, $window = 48, array $extenders = []) {
        $wantBefore = self::ctx_norm($context['before'] ?? '');
        $wantAfter  = self::ctx_norm($context['after']  ?? '');

// AICOBR_NAME_GUARD_2026_08 — the same $extenders the scan used. Without
        // this the guard would be advisory: a suggestion produced before a sibling
        // post existed could still be inserted afterwards, splitting a name the
        // scan would now refuse. Guarding both paths keeps "what you reviewed is
        // what gets written" true in both directions.
        foreach (self::find_matches($html, $phrase, 0, $extenders) as $cand) {
            $cur = self::occurrence_context($html, $cand['start'], $cand['end'], $window);
            if ($cur['before'] === $wantBefore && $cur['after'] === $wantAfter) {
                return $cand;
            }
        }
        return null;
    }

/** Tags and entities out, whitespace collapsed — display text only. */
 private static function flatten($html) {
 $t = preg_replace('/<[^>]*>/su', ' ', (string) $html);
 $t = html_entity_decode($t, ENT_QUOTES, 'UTF-8');
 return preg_replace('/\s+/u', ' ', $t);
 }

private static function mb_len($s) {
        return function_exists('mb_strlen') ? mb_strlen($s, 'UTF-8') : strlen($s);
    }

private static function mb_cut($s, $from, $len) {
        return function_exists('mb_substr') ? mb_substr($s, $from, $len, 'UTF-8') : substr($s, $from, $len);
    }

/** Local esc_attr so this file stays testable outside WordPress. */
    private static function esc_attr($s) {
        return function_exists('esc_attr')
            ? esc_attr($s)
            : htmlspecialchars((string) $s, ENT_QUOTES, 'UTF-8');
    }
}

}