fix(cua-driver)(windows): list empty-/null-title top-level windows (WPF, borderless, custom-chrome) (#2020)

[LaZzyMan]

Closes #2020.

Draft / direction check. This changes the Windows list_windows
enumeration contract, and I can't run the Windows test suite locally
(platform-windows needs an MSVC toolchain + a real interactive desktop;
see Verification below). Opening as a draft to confirm the direction —
replace the non-empty-title proxy with an explicit "is this a real window?"
predicate — before asking for a real-hardware regression run.

Problem

On Windows, list_windows silently dropped any visible top-level window whose
title is empty/null. Because get_window_state, click, scroll, etc. all
resolve a pid → windows through crate::win32::list_windows, such a window was
completely untargetable by the agent:

• debug_window_info {"pid": <pid>} listed the window (e.g. a WPF
  Ruler.Wpf.exe, class HwndWrapper[App.exe;;<guid>], hwnd 393542, title
  null).
• list_windows {"pid": <pid>} returned an empty array.
• get_window_state {"window_id": 393542} → "No window with window_id … exists".
• Every following click / scroll → "No windows found for pid <pid>".

WPF, borderless, and custom-chrome apps legitimately ship empty-caption
top-level windows, so this is a hard wall for a whole class of apps.

Root cause

Both enumeration sources hard-filtered on a non-empty title before the window
could reach the merged list:

• EnumWindows path — enum_windows_cb, win32/windows.rs (title_len == 0 → skip).
• UI Automation path — window_info_from_uia_element, uia/windows_enum.rs
  (title_len == 0 → None).

The module doc-comment even stated it as the contract: "Both sources apply the
same filters (visible, non-iconic, non-empty title)." This non-empty-title gate
was introduced as "filter parity" in #1542 (whose actual goal was the opposite —
UWP/WebView2 frames returning an empty array), and was never reconsidered for
honest untitled windows. Meanwhile debug_window_info (#1597) enumerated with a
looser filter (visible + no owner, title ignored), which is why the window showed
up there but nowhere else.

Fix

Replace the title proxy with an explicit predicate for "real, targetable
top-level window", shared by both enumeration sources so they can't drift
again (the drift was the root cause):

pub(crate) fn is_listable_top_level(hwnd: HWND) -> bool {
    // visible && !iconic && owner-less (GW_OWNER null) && !DWM-cloaked
}

• GW_OWNER null → excludes tool-tips / owned pop-ups / transient children
  (the EnumWindows path previously had no owner check — this is what lets us
  safely drop the title gate without admitting noise). Mirrors the top-level
  test debug_window_info already uses, so the two tools now agree.
• DWMWA_CLOAKED == 0 → excludes suspended-UWP / ApplicationFrameHost
  background frames that keep WS_VISIBLE but aren't on screen (the noise class
  feat(list_windows): UIA-first top-level window enumeration on Windows #1542 cared about).
• Title is now read for display only via a shared window_title helper; empty
  caption → empty string. The tool layer already renders (no title) for these
  records, so nothing downstream needed to change.

Touches: win32/windows.rs (predicate + helpers + enum_windows_cb),
uia/windows_enum.rs (reuse the predicate, drop the title gate),
PARITY.md (enumeration-source contract).

Tests

Added empty_title_top_level_window_is_listed in win32/windows.rs — creates a
real visible, owner-less, empty-caption top-level window via CreateWindowExW
and asserts it appears in list_windows(Some(own_pid)) with an empty title. It's
#[ignore] (needs an interactive window station), matching the existing Windows
GUI tests; run via the sandbox harness runner or
cargo test -p platform-windows -- --ignored empty_title.

Verification status

• ✅ cargo check -p platform-windows --target x86_64-pc-windows-gnu — clean (lib).
• ✅ cargo check … --tests — clean, including the new CreateWindowExW-based
  test module (the part I was least sure about, since it exercises Win32 API
  signatures directly). The only warning is a pre-existing unused import in
  impl_.rs, unrelated to this change.
• ✅ Static review against existing call sites (overlay.rs for
  CreateWindowExW/RegisterClassExW, impl_.rs for
  GetWindow(GW_OWNER).unwrap_or_default().is_invalid(), get_window_bounds
  for the DwmGetWindowAttribute shape).
• ⚠️ Not run on real Windows. Cross-check proves it compiles for the
  Windows target, but I have no rig / interactive desktop to execute the new
  #[ignore] test or run a real-desktop regression. The owner/cloaked gates'
  effect on real noise windows still needs a hardware run — ideally the same
  folks helping with Help wanted: validate multi-monitor (negative-X origin) fix on real Windows hardware — we have no local rig #1981.

Happy to adjust the predicate (e.g. add a non-zero-area check, or keep/drop the
cloaked gate) based on what a real run shows.

Summary by CodeRabbit

• Bug Fixes
  • Top-level windows with empty titles are now included in window listings when they meet the usual visibility and desktop-state checks.
  • Window enumeration is now more consistent across the app, reducing cases where detectable windows were hidden from lists.
  • Displayed window titles can now be blank instead of acting as a filter, improving accuracy for untitled windows.

[vercel]

@LaZzyMan is attempting to deploy a commit to the Cua Team on Vercel.

A member of the Team first needs to authorize it.

[coderabbitai]

Important

Review skipped

Auto incremental reviews are disabled on this repository.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 4d4dd017-4600-4490-be5b-f74d93f34470

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

📝 Walkthrough

Walkthrough

Windows top-level window enumeration now includes empty-caption HWNDs when they pass the shared visibility, ownership, and cloaking checks. The Win32 and UIA paths both use shared helpers, a regression test covers an untitled top-level window, and PARITY.md reflects the updated contract.

Changes

Windows top-level window listability parity

Layer / File(s)	Summary
Shared Win32 listability contract libs/cua-driver/rust/crates/platform-windows/src/win32/windows.rs, libs/cua-driver/rust/PARITY.md	list_windows now uses is_listable_top_level and window_title, empty captions are kept as display data, and a regression test covers an untitled visible top-level window.
UIA listability gate libs/cua-driver/rust/crates/platform-windows/src/uia/windows_enum.rs	window_info_from_uia_element now gates on is_listable_top_level, reads titles through the shared helper, and updates its comments and imports for empty-caption windows.

Sequence Diagram(s)

sequenceDiagram
  participant list_windows
  participant enum_windows_cb
  participant is_listable_top_level
  participant window_info_from_uia_element
  participant window_title
  list_windows->>enum_windows_cb: enumerate top-level HWNDs
  enum_windows_cb->>is_listable_top_level: filter visible, owner-less, non-cloaked HWNDs
  enum_windows_cb->>window_title: read caption for display
  window_info_from_uia_element->>is_listable_top_level: gate resolved HWND
  window_info_from_uia_element->>window_title: read caption for display

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

Possibly related PRs

• trycua/cua#1542: Introduced the Windows UIA/top-level enumeration filtering that this PR revises by allowing empty-caption HWNDs through the shared listability check.

Poem

I hopped where empty titles used to hide,
ახლა they sit in the list with rabbit pride.
One shared gate, one caption path,
and thump-thump windows join the path. 🐇

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the Windows fix for listing empty/null-title top-level windows and the affected window types.
Linked Issues check	✅ Passed	The PR matches #2020 by removing title-based filtering, aligning Win32/UIA enumeration, updating docs, and adding a regression test.
Out of Scope Changes check	✅ Passed	The changes are scoped to the Windows window-listing fix, with supporting refactors and tests that directly serve that goal.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@libs/cua-driver/rust/crates/platform-windows/src/win32/windows.rs`:
- Around line 294-330: The test window teardown in the CreateWindowExW flow is
not panic-safe because the precondition assertions in the window_title and
is_listable_top_level checks can panic before DestroyWindow runs. Add a cleanup
guard around the hwnd lifetime in this test path so the window is always
destroyed even if assert_eq! or assert! fails, and keep the existing
list_windows verification using hwnd as the unique handle reference.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: f29cc920-5271-4879-a5d2-cea21f902451

📥 Commits

Reviewing files that changed from the base of the PR and between 9e84c1d and d2027f8.

📒 Files selected for processing (3)

• libs/cua-driver/rust/PARITY.md
• libs/cua-driver/rust/crates/platform-windows/src/uia/windows_enum.rs
• libs/cua-driver/rust/crates/platform-windows/src/win32/windows.rs

[f-trycua]

Real, still-open bug (#2020) — main still drops empty-title top-level windows. The shared is_listable_top_level predicate is the right shape.

Blockers before merge: (1) it's conflicting against 0.7.0 — win32/windows.rs collides with the new UWP-host-resolution block, and PARITY.md was deleted on main (relocate or drop those doc edits); please rebase. (2) The new owner-less (GW_OWNER null) gate is a behavior change the old path never had — it could now drop owned-but-titled windows like modal "Save As" dialogs. That needs a real-Windows regression run to confirm it doesn't break dialog targeting. Rebase + validate and I'll take it. Keeping #2020 open.