gstack/browse/PLAN-snapshot-dropdown-interactive.md

Plan: Snapshot Dropdown/Autocomplete Interactive Element Detection

Problem

snapshot -i misses dropdown/autocomplete items on modern web apps. These elements:

1. Are often <div>/<li> with click handlers but no semantic ARIA roles
2. Live inside dynamically-created portals/popovers (floating containers)
3. Don't appear in Playwright's accessibility tree (ariaSnapshot())

The -C flag (cursor-interactive scan) was designed for this but:

• Requires separate flag — agents using -i don't get it automatically
• Skips elements that HAVE an ARIA role (even if the ARIA tree missed them)
• Doesn't prioritize popover/portal containers where dropdown items live

Root Cause

Playwright's ariaSnapshot() builds from the browser's accessibility tree. Dynamically-rendered popovers (React portals, Radix Popover, etc.) may not be in the accessibility tree if:

• The component doesn't set ARIA roles
• The portal renders outside the scoped body locator's subtree timing
• The browser hasn't updated the accessibility tree yet after DOM mutation

Changes

1. Auto-enable cursor-interactive scan with -i flag

File: browse/src/snapshot.ts

When -i (interactive) is passed, automatically include the cursor-interactive scan. This means agents always see clickable non-ARIA elements when they ask for interactive elements.

The -C flag remains as a standalone option for non-interactive snapshots.

if (opts.interactive) {
  opts.cursorInteractive = true;
}

2. Add popover/portal priority scanning

File: browse/src/snapshot.ts (inside cursor-interactive evaluate block)

Before the general cursor:pointer scan, specifically scan for visible floating containers (popovers, dropdowns, menus) and include ALL their direct children as interactive:

Detection heuristics for floating containers:

• position: fixed or position: absolute with z-index >= 10
• Has role="listbox", role="menu", role="dialog", role="tooltip", [data-radix-popper-content-wrapper], [data-floating-ui-portal], etc.
• Appeared recently in the DOM (not in initial page load)
• Is visible (offsetParent !== null or position: fixed)

For each floating container, include child elements that:

• Have text content
• Are visible
• Have cursor:pointer OR onclick OR role="option" OR role="menuitem"
• Tag with reason popover-child for clarity

3. Remove the hasRole skip in cursor-interactive scan

File: browse/src/snapshot.ts

Currently: if (hasRole) continue; — skips any element with an ARIA role, assuming the ARIA tree already captured it.

Problem: if the ARIA tree MISSED the element (timing, portal, bad DOM structure), it falls through both systems.

Fix: Only skip if the element's role is in INTERACTIVE_ROLES AND it was actually captured in the main refMap. Otherwise include it.

Since we can't easily check the refMap from inside page.evaluate(), the simpler fix: remove the hasRole skip entirely for elements inside detected floating containers. For elements outside floating containers, keep the hasRole skip as-is (to avoid duplicates in normal page content).

4. Add dropdown test fixture and tests

File: browse/test/fixtures/dropdown.html

HTML page with:

• A combobox input that shows a dropdown on focus/type
• Dropdown items as <div> with click handlers (no ARIA roles)
• Dropdown items as <li> with role="option"
• A React-portal-style container (position: fixed, high z-index)

File: browse/test/snapshot.test.ts

New test cases:

• snapshot -i on dropdown page finds dropdown items via cursor scan
• snapshot -i on dropdown page includes popover-child elements
• @c refs from dropdown scan are clickable
• Elements inside floating containers with ARIA roles are captured even when ARIA tree misses them

Rollout Risk

Low. The -C scan is additive — it only adds @c refs, never removes @e refs. The change to auto-enable it with -i increases output size but agents already handle mixed ref types.

One concern: The -C scan queries ALL elements (document.querySelectorAll('*')) which can be slow on heavy pages. For the popover-specific scan, we limit to elements inside detected floating containers, which is fast (small subtree).

Testing

cd /data/gstack/browse && bun test snapshot

Files Changed

1. browse/src/snapshot.ts — auto-enable -C with -i, popover scanning, remove hasRole skip in floating containers
2. browse/test/fixtures/dropdown.html — new test fixture
3. browse/test/snapshot.test.ts — new dropdown/popover test cases