Problem

When the user switches variants, the iframe's CSR app re-renders asynchronously and mutates every data-cslp attribute. If the visual editor pushes comment-icon highlights optimistically (before those mutations settle), two failure modes follow:

• Base → Variant: Icons are mounted against the stale base-CSLP element. After the CSR re-render the target element is gone; scroll-tracking falls back to its silent skip path and the icon drifts permanently.
• Variant → Base: The SDK's internal 15 × 60 ms = 900 ms retry window expires before the iframe finishes reverting to base CSLP values. The icon never appears.

Solution — pull-based, SDK-driven

This PR mirrors the highlight-variant pattern: the MutationObserver lives in the iframe (only place it can live because the iframe may be cross-origin from the visual editor), detects data-cslp changes, and signals the visual editor to re-send the highlight list. The VB owns the field-path list, so the SDK cannot re-mount icons on its own — it can only ask for a refresh.

1. REQUEST_DISCUSSION_HIGHLIGHTS postMessage event (postMessage.types.ts)

REQUEST_DISCUSSION_HIGHLIGHTS = "request-discussion-highlights",

Semantically names what the iframe is saying: "my CSLPs moved, please re-sync highlights."

2. Debounced emit from the existing observer (useRecalculateVariantDataCSLPValues.ts)

updateVariantClasses already sets up a MutationObserver per [data-cslp] element. We add a single fire-and-forget emit, debounced 200 ms so a burst of mutations coalesces into one request:

let highlightsRequestTimer: ReturnType<typeof setTimeout> | null = null;
const requestDiscussionHighlights = () => {
    if (highlightsRequestTimer !== null) clearTimeout(highlightsRequestTimer);
    highlightsRequestTimer = setTimeout(() => {
        highlightsRequestTimer = null;
        visualBuilderPostMessage?.send(
            VisualBuilderPostMessageEvents.REQUEST_DISCUSSION_HIGHLIGHTS
        );
    }, DISCUSSION_HIGHLIGHTS_DEBOUNCE_MS);
};
// ...inside MutationObserver callback after updateElementClasses():
requestDiscussionHighlights();

3. useVariantFieldsPostMessageEvent — SSR path (useVariantsPostMessageEvent.ts)

For SSR pages the DOM is already in its final state when the variant arrives — updateVariantClasses' observer will never fire. Emit the request immediately:

if (isSSR) {
    if (selectedVariant) { addVariantFieldClass(selectedVariant); }
    visualBuilderPostMessage?.send(
        VisualBuilderPostMessageEvents.REQUEST_DISCUSSION_HIGHLIGHTS
    );
} else {
    // CSR: the observer inside updateVariantClasses handles emission.
    updateVariantClasses();
}

4. Orphan cleanup in updateHighlightedCommentIconPosition (generateHighlightedComment.tsx)

Previously, if an icon's field-path no longer matched any [data-cslp] in the DOM (e.g. after a variant switch mutated attributes), the function silently skipped it — the icon stayed visible at its old position and drifted during scroll. Now it's removed immediately:

if (targetElement) {
    icon.style.top = `${top - highlighCommentOffset}px`;
    icon.style.left = `${left - highlighCommentOffset}px`;
} else {
    icon.remove(); // visual editor will re-mount via REQUEST_DISCUSSION_HIGHLIGHTS
}

This is independently correct even without the new event.

Why a pull (not a push)?

An earlier approach had the SDK emit a "DOM settled, proceed" gate event that the visual editor used to unblock a prequeued push. That worked but forced VB to carry cslpSettled state, a 5-second fallback, and an isVariantChangeRef skip-on-mount guard. The pull pattern is stateless on the VB side (just a listener) and self-heals for any cause of CSLP mutation — hydration, dynamic content, route changes — not only variant switches.

Tests

The MutationObserver → debounce → postMessage chain is an integration guarantee — jsdom does not reliably fire attribute mutations, so that end-to-end path is verified in the visual-editor DiscussionPage.spec.tsx tests (companion PR) where the listener is driven directly.

Full suite: 756 tests pass.

Companion PR

Visual editor: contentstack/visual-builder#2102

🤖 Generated with Claude Code