fix(cli): skip contrast for intentionally covered text

[miguel-heygen]

Summary

• Skip contrast candidates that explicitly allow occlusion while they are fully covered.
• Continue auditing the same text whenever any probe point is visible.
• Add regression coverage for both covered and visible states.

Root Cause

Contrast ignored the layout occlusion contract

Error: Fully covered copy marked data-layout-allow-occlusion produced repeated contrast_aa_failure findings.

Mechanism: The layout audit honors the explicit occlusion opt-out, but the contrast candidate walk only excluded data-layout-ignore, clipped-away, off-canvas, and hidden text. It therefore sampled the covering scene as the hidden text's background and reported meaningless low ratios.

Fix: Reuse the existing hit-test probe grid when an element or ancestor carries data-layout-allow-occlusion. Skip the candidate only when every probe point is covered; visible text still enters the contrast audit.

Changes

• packages/cli/src/commands/contrast-audit.browser.js: exclude fully covered intentional-occlusion candidates.
• packages/cli/src/commands/layout-audit.browser.test.ts: cover fully occluded and still-visible opt-out states.

Test Plan

• Exact 0.7.56 reproduction: layout passed while contrast emitted five false failures for fully covered text.
• Focused browser audit tests: 49 passed.
• Lint and format hooks passed.
• Workspace typecheck hook passed after generating the expected runtime artifact.

Confidence Score: 9/10

The fix is limited to the explicit data-layout-allow-occlusion contract and regression-tests both branches. CI remains the final cross-platform validation.

Source report: https://heygen.slack.com/archives/C0BGC335AQY/p1783980684706089