Skip to content

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

Merged
miguel-heygen merged 1 commit into
heygen-com:mainfrom
LeopoldTr:feat/inspect-text-occluded
Jun 15, 2026
Merged

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

Conversation

@LeopoldTr

Copy link
Copy Markdown
Contributor

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).

@miguel-heygen

Copy link
Copy Markdown
Collaborator

@LeopoldTr sign the commit to merge it pls

@LeopoldTr LeopoldTr force-pushed the feat/inspect-text-occluded branch from 6f0110f to 99e9130 Compare June 14, 2026 23:44
@jrusso1020

Copy link
Copy Markdown
Collaborator

@LeopoldTr needs a rebase and resolve merge conflicts it looks like after other PR was merged

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>
@LeopoldTr LeopoldTr force-pushed the feat/inspect-text-occluded branch from 99e9130 to 551bc1c Compare June 15, 2026 08:24
@miguel-heygen miguel-heygen merged commit 1e54827 into heygen-com:main Jun 15, 2026
36 checks passed
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.

3 participants