Interactive Overlay Masking Rules

Interactive overlays—popups, tooltips, hover states, vector-tile label layers, and dynamic markers—render asynchronously, respond to pointer events, and shift with every viewport transformation. They sit on top of the basemap you actually want to verify, so a naive pixel comparator treats each one as a defect. The result is a stream of persistent false positives that erode CI throughput and bury the genuine cartographic regressions you built the suite to catch. Solving this means writing masking rules that are deterministic, declarative, and tightly coupled to the rendering lifecycle of the mapping library in use, so that only stable geographic pixels reach the diff matrix.

This page extends the concepts in Dynamic Element Masking & UI Stability: where the parent reference establishes the contract between deterministic rendering and non-deterministic UI, this page is the concrete rule set for the volatile overlay category specifically—how to identify each overlay type, neutralize it in the correct rendering layer, and verify the exclusion held across runs.

What an Overlay Masking Rule Is

An overlay masking rule is a declarative binding between a target (a DOM selector or a coordinate region), a strategy (the mechanism used to neutralize it), and a lifecycle anchor (the event after which the rule may safely execute). Unlike a global diff tolerance, which loosens comparison everywhere, a masking rule removes a bounded part of the frame from comparison entirely while leaving the rest at full strictness. That precision is the whole point: the basemap stays gated at zero tolerance while a live cursor readout is excluded outright.

Two facts about web map rendering force the rule structure. First, overlays live in two different rendering substrates. DOM overlays—Leaflet’s L.Popup, MapLibre GL JS HTML markers, attribution controls—are real elements you can select and restyle. Canvas and WebGL overlays—measurement lines, highlight halos, heatmap layers drawn straight into the rendering context—have no DOM node at all and are invisible to CSS. A rule must declare which substrate its target lives in, because the neutralization mechanism is completely different. Second, overlays are time-dependent: a popup that is closed at load may open during an animation frame, and a hover tooltip exists only while a synthetic pointer hovers. The rule therefore carries a lifecycle anchor so the masking hook fires after the map reports idle and after the overlay has reached its final position, never mid-transition.

The standards that govern the underlying geometry are worth pinning down. Screen-space projection of a geographic feature relies on the map engine’s documented projection contract (map.project() in MapLibre/Mapbox GL, map.latLngToContainerPoint() in Leaflet), and canvas clipping follows the transformation-matrix rules in the MDN CanvasRenderingContext2D documentation. Viewport and layout-viewport scaling—the values that decide where a projected pixel actually lands—are specified in the W3C CSSOM View Module.

Architecture: A Declarative Masking Manifest

Masking configuration must never be hardcoded into individual test scripts. Inline selectors scattered through specs drift out of sync with the UI, and a single style refactor breaks dozens of files silently. The structural backbone is a centralized manifest, checked into the repository alongside the map style definitions, that maps test scenarios to exclusion rules:

# overlay-masking.yml — versioned next to the map style
test_suite: interactive_overlay_validation
masking_rules:
  - id: popup_hover_state
    selector: ".maplibregl-popup-anchor"
    substrate: dom
    strategy: css_visibility
    after: idle
  - id: live_attribution
    selector: ".mapboxgl-ctrl-attrib"
    substrate: dom
    strategy: placeholder
    after: load
  - id: vector_tile_labels
    selector: "canvas.map-render"
    substrate: webgl
    strategy: canvas_clip
    bounds:
      - type: geojson_feature
        id: "admin_boundaries"
      - type: screen_rect
        x: 1200
        y: 400
        w: 300
        h: 150

The manifest drives a single pre-snapshot executor rather than per-test logic. For dom substrate rules it injects a scoped stylesheet targeting the selector; for webgl rules it parses the bounds, projects any geographic features to viewport pixels with map.project(), and composes a clip path. Keeping the rules declarative buys version-controlled rule evolution, an audit trail in code review, and environment-specific overrides without touching core test code.

Declarative manifest driving a single substrate-aware executor A version-controlled overlay-masking manifest feeds one pre-snapshot executor that fires after the map idle event. The executor branches into two substrate paths: the DOM path injects a scoped stylesheet onto matched selectors, while the WebGL and canvas path projects geographic bounds to screen pixels and composes a clip path. Both paths converge on a single deterministic capture surface where only stable geographic pixels are compared. overlay-masking.yml version-controlled rule manifest Pre-snapshot executor one hook, fires after map idle DOM substrate inject scoped stylesheet visibility:hidden on matched selectors WebGL / Canvas substrate project geo bounds → screen px compose clip path · alpha-zero rect Deterministic capture surface only stable geographic pixels compared

Stable targeting over brittle selectors

A rule is only as durable as its target. Auto-generated class names and framework hashes change between builds, so a selector keyed to them silently stops matching and the overlay leaks back into the diff. Anchor rules to stable data attributes—data-testid, data-overlay-id—applied at the component level, and reserve framework class selectors (.leaflet-popup, .ol-overlay) only for third-party chrome you do not control.

Step-by-Step Implementation

The rule lifecycle below assumes a headless run that has already locked its viewport and device pixel ratio (covered under Viewport & Zoom Sync Strategies). The flow forks on substrate.

Substrate fork: DOM versus canvas neutralization A decision on overlay type forks two ways. A DOM popup, marker, or control is neutralized with CSS visibility hidden and pointer-events none applied after the map idle event. A canvas or WebGL draw call is neutralized by projecting its bounds and applying a clip or stencil mask. Both branches converge on one stable capture surface. Overlay type? DOM canvas DOM popup / marker / control visibility:hidden + pointer-events:none, after idle Canvas / WebGL draw project bounds, apply clip or stencil mask Stable capture surface

  1. Classify each overlay by substrate. Inspect the live DOM and the render canvas to decide whether a target is a real element or a context draw call. Anything you can select with document.querySelector and see in the elements panel is dom; anything that vanishes from the DOM but still paints is webgl/canvas.

  2. Wait for the lifecycle anchor before masking. Apply masks only after the map’s terminal render event, never during network transit or animation. Masking before idle captures a mid-transition overlay or lets the element re-inject after the mask is applied.

    // Resolve only when the map is fully settled, then mask.
await page.evaluate(() => new Promise((res) => map.once("idle", res)));

  3. Neutralize DOM overlays with a scoped stylesheet. Use visibility: hidden with pointer-events: none, not display: none. Collapsing the box with display: none reflows neighbouring nodes and can shift the map container itself—turning the mask into the regression you were avoiding. Await a repaint before capture.

    await page.addStyleTag({
  content: `.maplibregl-popup-anchor,
            .mapboxgl-ctrl-attrib {
    visibility: hidden !important;
    pointer-events: none !important;
  }`,
});

  4. Clip canvas and WebGL overlays in coordinate space. Context-drawn chrome has no DOM node, so CSS cannot touch it. Project the element’s geographic bounds to screen pixels, then exclude that rectangle—either with the Canvas 2D clip() path or by zeroing the alpha channel before the comparator reads the buffer.

    // Project a geo feature to a screen-space exclusion rect.
const sw = map.project(feature.bounds.getSouthWest());
const ne = map.project(feature.bounds.getNorthEast());
const rect = { x: sw.x, y: ne.y, w: ne.x - sw.x, h: sw.y - ne.y };
ctx.save();
ctx.beginPath();
ctx.rect(0, 0, canvas.width, canvas.height);
ctx.rect(rect.x, rect.y, rect.w, rect.h);
ctx.clip("evenodd"); // everything except the overlay rect

  5. Capture with the runner’s native mask option as a backstop. Playwright and Puppeteer paint opaque boxes over matched locators before encoding the screenshot, which composes cleanly with the manifest for DOM chrome.

    await page.screenshot({
  path: "baseline/city-overview.png",
  animations: "disabled",
  mask: [
    page.locator(".maplibregl-popup-anchor"),
    page.locator(".cursor-readout"),
  ],
  maskColor: "#101820",
});

  6. Stratify the comparison thresholds. A masked overlay is fully excluded, but the surviving regions still need per-zone tolerance rather than one global number—see the reference table below. The runtime mechanics of varying tolerance per scenario are covered in Dynamic Threshold Configuration, and the per-layer decision logic in Diff Algorithm Tuning for Cartography.

State must reach its final value before step 3 or 4 runs. Implementing Animation & Transition Suppression guarantees overlays settle into their computed position and opacity before the masking hook fires; without it, a clip path may capture a mid-transition frame and the exclusion boundary drifts between runs.

Alpha threshold for canvas exclusion

When zeroing a region instead of clipping it, the comparator should treat any pixel whose alpha falls below a small epsilon as excluded rather than as a black difference. Formally, a pixel at position is compared only when

so that fully and near-transparent masked pixels never enter the diff sum. Choosing slightly above zero absorbs the sub-percent alpha noise WebGL compositors emit at premultiplied edges.

Cross-Browser & Cross-Environment Considerations

Browser engines inject DOM nodes and apply CSS transforms differently, and they diverge sharply in subpixel rendering, font hinting, and WebGL pipelines. Chromium, WebKit, and Gecko each rasterize anti-aliased vector lines and label halos with their own algorithms, so a rule set tuned only on Chromium will leak fractional-pixel differences on the others. Standardize the headless environment before relying on any masking rule:

  1. Lock the viewport to a fixed resolution (for example 1280×800) and pin deviceScaleFactor.
  2. Force CPU rasterization with --use-gl=swiftshader --disable-gpu and --force-device-scale-factor=1 to remove GPU rasterization drift and DPR scaling artifacts.
  3. Inject a consistent @font-face stack to override OS-level font substitution.
  4. Disable animations and transitions globally via a prefers-reduced-motion override or an injected animation-duration: 0s style.

Containerize the runner so the GPU path, font packages, locale, and browser build are byte-identical across machines. A mask that matches in CI but not locally is almost always an environment mismatch rather than a selector fault—reproduce it by running the same container image locally before touching the rule. The broader artifact-suppression strategy these settings feed into lives in Noise Reduction for Map Artifacts, and the standardized automation capabilities they depend on are defined in the W3C WebDriver Specification.

Threshold & Parameter Reference

Pair deterministic masking with region-specific tolerance. A masked overlay is excluded entirely; everything that survives is gated by its own zone.

Zone Target elements Per-pixel threshold SSIM gate Disposition
Strict Basemap tiles, static vector geometry, grid lines 0.0 0.995 Compared at full strength
Relaxed Semi-transparent chrome, gradient fills, anti-aliased strokes 0.1–0.2 0.98 Browser rasterization noise tolerated
Masked Popups, tooltips, cursor readouts, loading spinners n/a n/a Excluded from the diff matrix
Alpha cutoff () Canvas-zeroed regions n/a n/a Pixels below 0.02 alpha ignored
Idle settle timeout Slow tile hydration before masking n/a n/a 5s–15s

A global tolerance of zero or one percent is insufficient for anti-aliased vector lines and WebGL compositing artifacts; a single permissive value hides real shifts. Encode tolerance per region, not per suite.

Common Pitfalls

  • Over-masking the container. Excluding the whole map element instead of the precise overlay region hides legitimate cartographic shifts and defeats the suite. Bound every rule to the smallest rectangle or selector that covers the volatile element.
  • Race-condition masking. Applying a mask before the idle event fires either misses an overlay that injects afterwards or captures it mid-transition. Always anchor the rule to a terminal render event.
  • Hardcoded, hash-based selectors. Targeting auto-generated class names that change between builds means the rule silently stops matching and the overlay leaks back in. Use stable data-* attributes.
  • display: none masking. Collapsing an overlay’s box reflows adjacent nodes and shifts the map container, manufacturing a baseline-wide diff. Prefer visibility: hidden plus a placeholder that preserves bounding-box dimensions.
  • Unversioned thresholds. Tying tolerance to environment variables without manifest tracking produces non-reproducible diffs across developer machines and CI runners. Keep thresholds in the versioned manifest and tag baselines with the manifest commit hash.

Establish a quarterly masking audit: remove deprecated selectors, re-validate coordinate-projection accuracy against the current map-library version, and recalibrate thresholds from aggregated false-positive metrics. When overlays render out of order because a deployment changed asset-load sequencing, pair these rules with Cache & CDN Invalidation Testing so tile-fetch latency does not shift overlay positioning inside the settle window. Spatial aggregation overlays such as heatmaps and dynamic point clusters add their own rebalancing variance during zoom and pan; keeping them reproducible is the subject of Marker Cluster Stability.

Frequently Asked Questions

Should I mask a popup or just close it before capture?

Close it if the closed state is the state under test—that gives you a real, comparable basemap with no exclusion. Mask it only when the popup must stay open for the scenario (for example verifying that opening it does not shift surrounding tiles) but its dynamic contents—timestamps, live values—carry no cartographic meaning. Every masked region is a region you are no longer testing, so prefer removing the source of variance over hiding it.

Why does CSS masking miss my measurement line or highlight halo?

Because those overlays are drawn directly into the WebGL or Canvas2D context and have no DOM node to select. CSS-based rules only reach real elements. Project the overlay’s geographic bounds to screen space with map.project() and apply a clip path or alpha-zero the rectangle before comparison, exactly as the canvas branch of the implementation describes.

How do I keep overlay rules from drifting out of sync with the UI?

Centralize them in a version-controlled manifest keyed to test scenarios, and target stable data-* attributes instead of framework-generated class hashes. A UI refactor then updates one file, code review surfaces the masking change alongside the markup change, and a renamed class cannot silently leave an overlay unmasked.

What's the right threshold for the regions around a masked overlay?

Do not use one global number. Gate the static basemap and vector geometry at zero per-pixel tolerance with an SSIM floor around 0.995, relax anti-aliased chrome to roughly 0.1–0.2 per-pixel with SSIM near 0.98, and exclude the volatile overlay outright. Tune the exact values per layer following Diff Algorithm Tuning for Cartography.