Skip to content

fix(extension): avoid overlapping page controls - #34

Merged
kunchenguid merged 12 commits into
mainfrom
fix/avoid-button-overlap
May 15, 2026
Merged

kunchenguid merged 12 commits into
mainfrom
fix/avoid-button-overlap

Conversation

@kunchenguid

Copy link
Copy Markdown
Owner

Intent

The developer wanted the Simple Words floating “sw” brand button to avoid visually and interactively overlapping with existing page controls near the active editor. They specifically required collision detection to focus on actual button-like clickable elements, not plain input or textarea fields, since the active drafting area should not block placement. They also pushed back on using broad [tabindex] avoidance because it would catch too many non-control containers and make positioning unstable. The intended change was to make placement collision-aware while excluding the active editor and avoiding only narrow selectors such as buttons, links, role-based buttons/menu items/options, submit/reset/button inputs, and summaries.

What Changed

  • Adds collision-aware floating button placement that tries nearby candidate positions when the default lower-right placement overlaps visible button-like page controls.
  • Limits avoidance to actual clickable controls such as buttons, links, role-based menu/button/option controls, button inputs, and summaries while excluding the active editor, injected UI, invisible controls, and broad tabindex containers.
  • Adds unit and Playwright coverage for overlap avoidance, small/interior collisions, bounded hit testing, and updates Simple Words design docs to reflect the new placement behavior.

Risk Assessment

✅ Low: The change is well-bounded to floating button placement, uses narrow clickable selectors with visibility filtering, and now short-circuits collision probing to limit refresh-path overhead.

Testing

  • Summary: Exercised the Simple Words floating button end-to-end in Chromium against a real fixture: it moved away from an overlapping page button and did not avoid a broad tabindex container.
  • npx vitest run test/uiPosition.test.ts test/content.test.ts -t "button|overlap|tabindex|position"
  • npx playwright test e2e/button-overlap.spec.ts
    Button-like page control avoided

Button-like page control avoided
Broad tabindex container not avoided

Broad tabindex container not avoided

Placement rectangle evidence

{"buttonControlEvidence":{"simpleWordsButton":{"top":169,"left":248,"right":272,"bottom":193},"avoidTarget":{"top":221,"left":240,"right":290,"bottom":271},"overlapsAvoidTarget":false},"tabindexEvidence":{"simpleWordsButton":{"top":229,"left":248,"right":272,"bottom":253},"avoidTarget":{"top":221,"left":240,"right":290,"bottom":271},"overlapsAvoidTarget":true}}
  • Outcome: ⚠️ 1 info across 1 run (2m44s)

Pipeline

Updates from git push no-mistakes

✅ **intent** - passed

Round 1 - passed ✅

✅ **Rebase** - passed

Round 1 - passed ✅

🔧 **Review** - 1 issue found → auto-fixed (9)

Round 1 - found 1 warning

  • ⚠️ src/content.ts:580 - Collision detection treats any matching element with a layout box as an obstacle, including controls hidden with visibility: hidden; those invisible/non-interactive controls can push the Simple Words button away from otherwise valid placements. Filter out elements whose computed visibility is hidden/collapsed before adding their rects.

Round 2 (auto-fix) - found 1 warning

  • ⚠️ src/content.ts:574 - Button repositioning now scans every matching button/link-like element in the whole document and reads computed style plus layout for each one on every active-editor refresh, including scroll and resize paths. On pages with many links or controls this can introduce scroll/typing jank; constrain collision checks to candidate positions or otherwise avoid full-document layout reads for each refresh.

Round 3 (auto-fix) - found 1 warning

  • ⚠️ src/content.ts:641 - Collision discovery only samples the candidate button rect at its four corners and center, so a real page control that partially overlaps the future Simple Words button without covering one of those five points will not be included in avoidRects and the button can still be placed on top of it. Sample enough of the candidate area or use a small bounding query/fallback for candidate regions rather than five points.

Round 4 (auto-fix) - found 1 warning

  • ⚠️ src/content.ts:643 - Overlap discovery now calls elementsFromPoint for every pixel of each candidate button rectangle on every button reposition. With six candidates this is roughly 2,600-3,700 hit-tests per input, selectionchange, scroll, or resize while an editor is active, which can still cause page jank; replace the per-pixel grid with a bounded coarser sample plus targeted edge/center coverage, or debounce scroll-driven repositioning.

Round 5 (auto-fix) - found 1 warning

  • ⚠️ src/content.ts:639 - The bounded overlap scan samples each candidate at 8px intervals, so a small button-like control that overlaps the future Simple Words button between those sample rows/columns can still be missed and covered. Add deterministic coverage for small overlaps, such as sampling all candidate edges plus center bands at a tighter bound or falling back to measuring discovered nearby selector matches for the candidate region.

Round 6 (auto-fix) - found 1 warning

  • ⚠️ src/content.ts:639 - The collision pass now performs a dense 2px hit-test grid over all six candidate button rectangles, and positionButton runs from focus/input/selection plus scroll and resize refresh paths. That is about 1,000 elementsFromPoint calls per refresh for a 24px button, which can still introduce typing or scroll jank on complex pages; keep deterministic overlap coverage without scanning every 2px cell, or debounce refreshes driven by scroll/resize.

Round 7 (auto-fix) - found 1 warning

  • ⚠️ src/content.ts:643 - The overlap discovery samples only the candidate rectangle perimeter plus one vertical center line, so a small clickable control fully inside the future Simple Words button area but away from those sampled lines is never added to avoidRects and can still be covered. Add deterministic interior coverage, such as a bounded grid or a targeted fallback that checks nearby selector matches against each candidate rect.

Round 8 (auto-fix) - found 1 warning

  • ⚠️ src/content.ts:644 - Button positioning still performs 804 elementsFromPoint hit-tests per refresh for a 24px button because every candidate samples full top/bottom edges, three vertical lines, and an interior grid. Since positionButton is called from focus, input, selectionchange, scroll, and resize paths, this can cause typing or scroll jank on complex pages; keep bounded collision discovery but avoid probing every candidate so densely on every refresh, for example by throttling scroll/resize refreshes or only expanding sampling after a coarse collision hint.

Round 9 (auto-fix) - found 1 warning

  • ⚠️ src/content.ts:598 - Collision probing eagerly samples the entire candidate rectangle before knowing whether that candidate is blocked, so each blocked candidate still costs roughly 139 elementsFromPoint calls and a worst-case refresh can probe all six candidates on scroll, resize, selection, or input. Short-circuit candidate probing as soon as a visible matching clickable element overlapping that candidate is found, or use a cheaper coarse pass before dense sampling.

Round 10 (auto-fix) - passed ✅

⚠️ **Test** - 1 info

Round 1 - found 1 info

  • ℹ️ e2e/button-overlap.spec.ts - new test file written by agent: e2e/button-overlap.spec.ts
  • npx vitest run test/uiPosition.test.ts test/content.test.ts -t "button|overlap|tabindex|position"
  • npx playwright test e2e/button-overlap.spec.ts
🔧 **Document** - 1 issue found → auto-fixed

Round 1 - found 1 warning

  • ⚠️ .agents/skills/simple-words-design/ui_kits/extension/README.md:9 - The UI kit documentation still describes production placement as a compact sw button near the lower-right edge of focused editable fields. The code now uses collision-aware placement: it starts from the lower-right candidate but can move to other candidate positions to avoid overlapping button-like page controls while excluding the active editor. Update this production-positioning note, and the duplicate statement on line 36, so design/prototype guidance does not preserve a stale lower-right-only behavior.

Round 2 (auto-fix) - passed ✅

✅ **Lint** - passed

Round 1 - passed ✅

✅ **Push** - passed

Round 1 - passed ✅

@kunchenguid
kunchenguid merged commit 8ae0b8d into main May 15, 2026
1 check passed
@kunchenguid
kunchenguid deleted the fix/avoid-button-overlap branch May 15, 2026 21:07
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.

1 participant