Skip to content

feat(cli): flag text occluded by opaque elements in inspect#1435

Open
LeopoldTr wants to merge 1 commit into
heygen-com:mainfrom
LeopoldTr:feat/inspect-text-occluded
Open

feat(cli): flag text occluded by opaque elements in inspect#1435
LeopoldTr wants to merge 1 commit into
heygen-com:mainfrom
LeopoldTr:feat/inspect-text-occluded

Conversation

@LeopoldTr

Copy link
Copy Markdown

Problem

hyperframes inspect reports 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_occluded check to the layout audit. For each text-bearing element it sweeps a grid across the text box (three rows × nine columns) and uses document.elementFromPoint to 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, both rgba(r, g, b, a) and modern rgb(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 with clipped_text), and a fix hint. Opt out of intentional layering with data-layout-allow-occlusion, mirroring the existing data-layout-allow-overflow / data-layout-ignore escape hatches (documented in docs/packages/cli.mdx).

Testing

  • New unit tests in 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.
  • Full @hyperframes/cli suite green (771 tests); typecheck, oxlint, oxfmt, and the fallow audit gate all pass.

Note

The two *.browser.js audit scripts are added to the fallow entry list — they are read as raw strings and injected via page.addScriptTag, so they have no import-graph referrer (same pattern already used for packages/core/src/runtime/entry.ts).

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>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants