feat(cli): flag text occluded by opaque elements in inspect#1435
Open
LeopoldTr wants to merge 1 commit into
Open
feat(cli): flag text occluded by opaque elements in inspect#1435LeopoldTr wants to merge 1 commit into
LeopoldTr wants to merge 1 commit into
Conversation
The layout audit only reported boxes that overflow their container; text that fits perfectly but is painted over by a later sibling or overlay was never caught. Add a text_occluded check that sweeps a grid across each text box (three rows x nine columns) and, via elementFromPoint, flags text whose topmost element is an unrelated opaque element (raster content, background image, or a solid background at near-full opacity). Low-opacity overlays such as scrims and grain are exempt. Opt out of intentional layering with data-layout-allow-occlusion. The two *.browser.js audit scripts are added to the fallow entry list: they are injected by path via page.addScriptTag, so they have no import-graph referrer. Co-authored-by: Miguel Ángel <miguel07alm@protonmail.com>
This was referenced Jun 14, 2026
miguel-heygen
approved these changes
Jun 14, 2026
Collaborator
|
@LeopoldTr sign the commit to merge it pls |
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 inspectreports text that overflows its box, but never text that fits perfectly yet is painted over by a later sibling or overlay. A headline at full opacity, correctly sized and inside its container, can be completely hidden behind a foreground panel/image and the audit stays green. This is the failure mode the overflow checks structurally can't see.Solution
Add a
text_occludedcheck to the layout audit. For each text-bearing element it sweeps a grid across the text box (three rows × nine columns) and usesdocument.elementFromPointto find the topmost element at each sample. If that element is foreign (not the text itself, its own subtree, or an ancestor) and opaque, the text is reported as hidden beneath it."Opaque" means painting near-full-opacity pixels: raster content (
img/video/canvas), a background image, or a solid background colour (alpha > 0.6, bothrgba(r, g, b, a)and modernrgb(r g b / a)syntaxes). Low-opacity overlays such as scrims and grain are intentionally exempt, and the three-row sweep catches overlays that cover only part of a multi-line block.The finding carries the occluder in
containerSelector(consistent with the other multi-element findings),severity: "error"(consistent withclipped_text), and a fix hint. Opt out of intentional layering withdata-layout-allow-occlusion, mirroring the existingdata-layout-allow-overflow/data-layout-ignoreescape hatches (documented indocs/packages/cli.mdx).Testing
layout-audit.browser.test.ts: flags an opaque sibling overlay (asserts selector + occluder), ignores low-opacity scrims, respects the opt-out, and does not flag text that is itself the topmost element.@hyperframes/clisuite green (771 tests); typecheck, oxlint, oxfmt, and the fallow audit gate all pass.Note
The two
*.browser.jsaudit scripts are added to the fallowentrylist — they are read as raw strings and injected viapage.addScriptTag, so they have no import-graph referrer (same pattern already used forpackages/core/src/runtime/entry.ts).