feat(cli): flag overlapping text blocks in inspect#1436
Open
LeopoldTr wants to merge 1 commit into
Open
Conversation
The layout audit compares each element against its container, so two text blocks that collide with each other — neither overflowing its own box — render unreadable yet pass clean. Add a content_overlap check that pairs up the solid text blocks and reports any two whose boxes intersect by more than a fifth of the smaller box. Watermark-style text (low colour alpha) is decorative and exempt; opt out of intentional stacking with data-layout-allow-overlap. Co-authored-by: Miguel Ángel <miguel07alm@protonmail.com>
miguel-heygen
approved these changes
Jun 14, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Problem
hyperframes inspectcompares each element against its container (overflow, clipping). It never compares two siblings against each other, so two text blocks that collide — each sitting perfectly inside its own box — render unreadable yet the audit stays green. Stacked headings, a caption landing on a title, two labels animating into the same spot: all invisible to the current checks.Solution
Add a
content_overlapcheck. After the overflow passes, it collects the solid text blocks (visible, text-bearing, not watermark-faint) and reports any pair whose text boxes intersect by more than a fifth of the smaller box. The finding names both blocks (selector+containerSelector), is ratederror(same asclipped_text— both make text unreadable), and carries a fix hint.Exemptions keep it quiet on intentional design:
data-layout-allow-overlap, mirroring the existingdata-layout-allow-overflow/data-layout-ignoreescape hatches (documented indocs/packages/cli.mdx).The check reuses the audit's existing visibility, text-rect, and selector helpers, and runs alongside the overflow passes in
__hyperframesLayoutAudit— no extra Chrome launch or timeline pass.Testing
layout-audit.browser.test.ts: flags two overlapping blocks (asserts both selectors), ignores sub-threshold overlap, ignores low-alpha watermark text, and respects the opt-out.@hyperframes/clisuite green (771 tests); typecheck, oxlint, oxfmt, and the fallow audit gate all pass.Note
Independent of #1435 (text occlusion) — both extend the same audit but touch disjoint logic and can land in either order.