SERP overlay implementation handoff

1. Destination URL

Required outcome: identify each result by its actual destination, never by an address reconstructed from Google’s displayed breadcrumb.

Confirmed problem: resolveResultUrl() prefers extractCiteUrl() over the title link. Tests with the supplied code collapse distinct /a and /b pages into one domain, or invent /Products/Widget instead of the real /products/detail?id=42 destination.

Implementation guidance

1. Use the title anchor already selected by findHeadingLink(). Parse its non-empty href against the document base URL. Remove breadcrumb reconstruction from URL identity; do not fall back to it when a link is missing or invalid.
2. Unwrap only recognized Google-hosted redirects. For supported /url links, extract a valid q or url destination and validate it again. Do not unwrap a third-party site merely because its path is /url. Keep existing ad and result-eligibility exclusions.
3. Accept only a resolved, eligible HTTP(S) destination. If a redirect form cannot be resolved safely, skip that URL-dependent overlay/export row; do not send Google’s redirect URL to the metric service. Add a captured fixture before supporting another redirect form such as /goto.
4. Use the resolved URL consistently for result identity, CSV URLs and inputs to page-level metrics/report links. Keep domain-level metrics domain-scoped. Preserve the destination’s path and query; do not merge different pages by domain or displayed breadcrumb.

Follow the URL through the shared helpers. normalizeSemrushTarget() currently calls normalizeUrl(), which removes every query parameter. A resolver-only fix therefore does not preserve ?id=42 versus ?id=43 in page-level requests and report targets. Preserve query identity in the page-target path and test its callers, caches and generated requests. Do not globally change the shared normalizer without regression checks. This is an existing shared dependency, not established as a new SERP regression.

Source: URL resolution · detection and deduplication · metric target normalization · shared URL normalizer. Legacy 3.13.5 read the selected result link’s href directly; it did not reconstruct the breadcrumb.

2. Result numbering & exports

Required outcome: overlay positions and CSV rows must come from the same current, page-ordered list of eligible results.

Confirmed problem: added subtrees are scanned and numbered independently, then merged. In the supplied-code test, a fourth result becomes another #1; a whole-page scan gives #4. Removing an overlay’s metric snapshot does not remove its separate export row.

Implementation guidance

1. After each relevant debounced mutation batch, run one complete detection pass for the current page and use the replacement path: replaceSerpExportRows() plus syncSerpOverlays(). Do not merge independently numbered partial scans.
2. Number accepted, connected results in DOM order using the existing pagination offset. Preserve the current policy of one result per exact resolved URL, keeping its first accepted occurrence; this change does not introduce a new duplicate-card policy.
3. Reconcile export membership, mounted overlays and metric snapshots together. Remove departed results and update retained positions. Preserve unchanged result state; do not clear/reload all metrics on every mutation. When a URL’s container or insertion anchor changes, reposition its existing host/root when possible. If remounting is necessary, retain or reuse loaded metric state for the unchanged URL; a connected host alone does not prove correct placement.
4. Keep debouncing and the existing generation guards. Cover additions, removals, DOM moves and result-link href changes; the current observer watches child-list changes only. Filter SEOquake’s own DOM updates to avoid feedback loops. Invalidate obsolete async work on URL/lifecycle resets so old work cannot overwrite the current page.
5. Before Export reads the store, flush or run the current reconciliation and wait for it to finish. Capture rows, metric snapshots and search-query filename from the same current-page generation. Do not wait for every metric to load: retain existing n/a versus zero behavior.

Source: mutation orchestration · observer · result stores · overlay reconciliation · export action · CSV assembly. File links use the inspected revision; the async, placement and export-timing items are implementation safeguards, not additional reproduced live failures.